feat: Migrate Maturity Metadata to Registry and Remove from Frontmatter

[katriendg]

Issue Description

Migrate the maturity field from artifact frontmatter to the AI Artifacts Registry and update all validation scripts, packaging workflows, and documentation that reference maturity frontmatter. This resolves Copilot CLI compatibility issues caused by custom frontmatter fields.

Motivation

The maturity frontmatter field blocks all HVE-Core agents from working in Copilot CLI. Once the registry (Phase 1) is in place, this migration removes maturity from frontmatter and updates all dependent systems to read from the registry instead.

Related: #360 - Custom maturity frontmatter breaks Copilot CLI

Dependencies

• Requires: feat: AI Artifacts Registry Design and Schema #432 (Phase 1: AI Artifacts Registry Design and Schema)

Deliverables

1. Extension Packaging Script Updates — Deferred to Phase 2 (#433)

Packaging script changes (Prepare-Extension.ps1) are deferred to Phase 2 (Multi-Package Extension Build System), which already restructures the packaging scripts for collection manifests. Deferral is safe because Get-FrontmatterData defaults maturity to "stable" when absent from frontmatter, producing identical behavior to today (all 61 artifacts use maturity: stable). The existing Pester test "Defaults maturity to stable when not specified" validates this fallback path.

2. Frontmatter Schema Updates

Update schemas in scripts/linting/schemas/ to remove maturity:

• agent-frontmatter.schema.json - Remove maturity property and enum
• instruction-frontmatter.schema.json - Remove maturity property
• prompt-frontmatter.schema.json - Remove maturity property
• skill-frontmatter.schema.json - Remove maturity property (if present)

3. Artifact Frontmatter Removal

Remove maturity field from all artifact files:

Artifact Type	Estimated Files	Location
Agents	21	.github/agents/
Instructions	17+	.github/instructions/
Prompts	22+	.github/prompts/
Skills	1	.github/skills/

4. Validation Script Updates

No script changes needed — Validate-MarkdownFrontmatter.ps1 uses generic JSON Schema validation with no hardcoded maturity logic. Once schemas are updated (Deliverable 2), maturity validation is automatically removed from frontmatter checks. The registry's npm run lint:registry (from Phase 1) validates maturity values.

5. CI Workflow Updates

No workflow changes needed — the only maturity reference in .github/workflows/extension-package.yml is a comment in the channel input description. No functional code references maturity directly.

6. Documentation Updates

Update documentation that references maturity frontmatter:

• docs/contributing/custom-agents.md - Remove maturity frontmatter guidance
• docs/contributing/instructions.md - Remove maturity frontmatter guidance
• docs/contributing/prompts.md - Remove maturity frontmatter guidance
• docs/contributing/skills.md - Remove maturity frontmatter guidance
• docs/contributing/ai-artifacts-common.md - Update to reference registry for maturity
• .github/instructions/prompt-builder.instructions.md - Remove "ignore VS Code validation warnings for maturity" guidance

7. Pester Test Updates — Deferred to Phase 2 (#433)

Pester test updates for registry-based maturity are deferred alongside the packaging script changes. Existing tests continue to pass because Get-FrontmatterData still returns maturity (defaulting to "stable" when absent).

Acceptance Criteria

• maturity field removed from all 61 artifact files
• Frontmatter schemas no longer include maturity property
• chatmode-frontmatter.schema.json maturity property also removed
• npm run lint:frontmatter passes without maturity in artifacts
• Extension packaging still produces correct packages (via Get-FrontmatterData stable default)
• Contributing documentation updated to reference registry for maturity
• Prompt-builder instructions no longer mention ignoring maturity warnings
• Agents load in VS Code without frontmatter validation warnings
• (Stretch) Agents work in Copilot CLI without rejection

Deferred to Phase 2 (#433):

• Prepare-Extension.ps1 reads maturity from registry instead of frontmatter
• Pester tests updated for registry-based maturity discovery

Technical Notes

• All current artifacts have maturity: stable so frontmatter removal is safe
• Get-FrontmatterData (L121) defaults $maturity = "stable" when absent — packaging works unchanged
• Extension channel filtering logic in Get-AllowedMaturities remains unchanged
• Backward compatibility not required per project conventions
• 6 schemas contain maturity: agent, instruction, prompt, chatmode, skill frontmatter schemas (remove) + registry schema (keep)

Additional Context

• Current maturity usage: scripts/extension/Prepare-Extension.ps1 lines 65-83, 175-213 (deferred to Phase 2)
• Prompt-builder workaround: .github/instructions/prompt-builder.instructions.md line 225
• All artifacts currently use maturity: stable (no preview or experimental artifacts exist)
• Research document: .copilot-tracking/research/2026-02-06-maturity-migration-research.md

[katriendg]

This issue has been resolved in #519 (PR #439). Maturity was successfully removed from all artifact frontmatter and schemas. The original plan moved maturity to the registry, but the registry was subsequently replaced by collection manifests. Maturity is now tracked per-item in collections/*.collection.yml. The core goal — fixing Copilot CLI compatibility — is fully achieved.

Closing as completed.