feat(scripts): promote docs frontmatter fields from recommended to required

[Jamie Kim (jkim323)]

Pull Request

Description

Promotes author, ms.date, ms.topic, and keywords from recommended to required for every page under docs/**, and closes the docs/reference/** validation gap introduced by #2389.

Schema

docs-frontmatter.schema.json required grows from ["title", "description"] to ["title", "description", "author", "ms.date", "ms.topic", "keywords"]. author gains minLength: 1, and the four property descriptions change from Recommended: to Required:. A missing trailing newline is also fixed.

Validator

Test-DocsFileFields replaces its split required/suggested logic with a single $requiredFields list that mirrors the schema required array, so docs/** is governed identically whether or not schema validation is enabled. This mirroring is load-bearing: PR CI runs the validator without -EnableSchemaValidation, so the script path is what actually enforces the new fields.

ADR pages matching docs/planning/adrs/NNNN-*.md are carved out of the keywords requirement. adr-frontmatter.schema.json is a closed schema (additionalProperties: false) that categorizes with tags and declares no keywords property, so requiring it there would be unsatisfiable.

Exclusion move

docs/reference/** is removed from ExcludePaths in Validate-MarkdownFrontmatter.ps1, returning the asset-catalog tree to frontmatter validation. It is added to FooterExcludePaths because generated pages carry no Copilot attribution footer and the generator does not emit one.

Generator

New-DocFrontmatter gains required -Topic (constrained by a ValidateSet matching the schema enum, so generator output cannot drift from the schema) and -Keywords, plus an optional -Author defaulting to Microsoft. A new pure helper Get-AssetDocKeyword derives each page's keywords from asset kind, owning collection segment, and artifact key, deduplicated case-insensitively and order-stable. Index pages pass explicit keywords. Call sites use splatting so the preserved-date and advanced-date paths stay in sync. asset-doc.template.md is updated to match.

Backfill

262 generated pages under docs/reference/**, plus legacy pages under docs/templates/, docs/contributing/, docs/planning/, and docs/docusaurus/, now carry all six fields. This lets the repo-wide required check pass without a big-bang failure rather than scoping enforcement to changed files only.

Documentation

docs/contributing/documentation-maintenance.md gains a Requirements section listing all six fields with their constraints, the ADR tags-not-keywords exception, and a note that docs/reference/ frontmatter is generator-owned and must not be hand-edited.

Breaking change

keywords was previously unchecked entirely — neither required nor warned — so any docs/** page missing it now fails validation. New-DocFrontmatter and New-IndexContent also gain mandatory parameters. All in-repo pages and callers are updated in this PR; external callers of those functions would need updating.

Related Issue(s)

Closes #2467

• Reverses the docs/reference/** exclusion introduced by feat(docs): scaffold asset docs pages and wire Docusaurus Asset Catalog #2389
• Sequenced after feat: [5/7] enforce asset docs in npm scripts and PR CI gate #2337 (warnings-as-errors), which is already rolled out

Type of Change

Select all that apply:

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with hve-builder and addressed all actionable findings
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)
• Copilot hook (.github/hooks/*/*.json)
• Eval spec added/updated for changed AI artifacts (evals/)

Note for AI Artifact Contributors:

• Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.
• Skills: Must include both bash and PowerShell scripts. See Skills.
• Model Versions: Contributions MUST target models listed in the model catalog (scripts/linting/model-catalog.json) whose provider appears in providerAllowlist and whose status is ga or preview. Run npm run lint:models to validate references.
• See Agents Not Accepted and Model Version Requirements.

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Sample Prompts (for AI Artifact Contributions)

User Request:

Execution Flow:

Output Artifacts:

Success Indicators:

For detailed contribution requirements, see:

• Common Standards: docs/contributing/ai-artifacts-common.md - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing
• Agents: docs/contributing/custom-agents.md - Agent configurations with tools and behavior patterns
• Prompts: docs/contributing/prompts.md - Workflow-specific guidance with template variables
• Instructions: docs/contributing/instructions.md - Technology-specific standards with glob patterns
• Skills: docs/contributing/skills.md - Task execution utilities with cross-platform scripts

Testing

Automated validation run locally against this branch:

Command	Result
npm run lint:frontmatter	Pass — 1102 files validated, 0 errors, 0 warnings
npm run test:ps -- -TestPath scripts/tests/linting/	Pass — 1132 passed, 0 failed, 34 not run
npm run test:ps -- -TestPath scripts/tests/docs/	132 passed, 4 failed — pre-existing, see Additional Notes
npm run lint:asset-docs	Pass — 257 assets evaluated, 0 errors, 256 pre-existing stub warnings
npm run lint:json	Pass — 54 JSON files, strict parse clean
npm run lint:adr-consistency	Pass — 9 files, 0 errors, 0 warnings

npm run lint:frontmatter runs with -WarningsAsErrors -EnableSchemaValidation, so the run above exercises both the script-level required-field checks and the tightened schema across the whole repository.

New test coverage added in this PR:

• New-DocFrontmatter emits all six fields, honors an explicit author, and rejects a topic outside the schema enum.
• Get-AssetDocKeyword combines kind, collection, and key; omits the collection segment for assets directly under the kind directory; deduplicates case-insensitively.
• Test-DocsFileFields returns one error per missing required field, errors on an empty keywords array, skips keywords for

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable)

AI Artifact Contributions

• Used hve-builder review mode to review contribution
• Addressed all actionable findings from the hve-builder review
• Verified contribution follows common standards and type-specific requirements

Required Local Checks

The following local-safe validation commands must pass before merging:

• Local validation aggregate: npm run validate:local
• Documentation validation (if docs changed): npm run validate:docs
• Spell checking: npm run spell-check
• Link validation: npm run lint:md-links

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues
• Security-related scripts follow the principle of least privilege

Additional Notes

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.12%. Comparing base (197afb8) to head (3fbafff).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2603      +/-   ##
==========================================
+ Coverage   83.10%   83.12%   +0.01%     
==========================================
  Files         164      164              
  Lines       22254    22284      +30     
  Branches       29       29              
==========================================
+ Hits        18495    18524      +29     
- Misses       3756     3757       +1     
  Partials        3        3              

Flag	Coverage Δ
docusaurus	95.07% <ø> (ø)
pester	86.52% <ø> (+0.03%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 4 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Eval Execution

✅ Status: Passed

• Artifacts evaluated: 0
• Specs run: 0
• Assertions passed: 0
• Assertions failed (blocking): 0
• Assertions failed (advisory): 0
• Failed specs (merge-blocking): 0

No changed AI artifacts required evaluation.