microsoft / microsoft/hve-core
docs: update docs/customization/collections.md Maturity Filtering section for removed tier
- Dominant language
- Python
- Stars
- 1.5k
- Forks
- 301
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 92
Description
**Component:** Documentation
**Bug Description**
`docs/customization/collections.md` describes only four maturity tiers in the Maturity Filtering section, but the `collections/security.collection.yml` manifest now uses a fifth tier (`removed`) introduced by commit `19adc30` (feat(skills): add removed maturity tier and retire owasp-docker, #1444).
The schema at `scripts/linting/schemas/collection-manifest.schema.json` now enumerates `stable`, `preview`, `experimental`, `deprecated`, and `removed` at both the collection level and item level.
**What the documentation currently says:**
> Collections support **four** maturity tiers that control inclusion in generated plugin output:
| Tier | Meaning | Plugin Inclusion |
|----------------|--------------------------------------------|-----------------------------|
| `stable` | Production-ready, fully tested | Included in all channels |
| `preview` | Feature-complete but undergoing validation | Included in all channels |
| `experimental` | Early-stage, may change significantly | Excluded from stable builds |
| `deprecated` | Scheduled for removal | Excluded from new builds |
The hve-core-all Superset section also only mentions `maturity: experimental` and `maturity: deprecated` without acknowledging `removed` artifacts.
**Expected Behavior**
The Maturity Filtering section should say "five maturity tiers" and add a `removed` row:
| `removed` | Retired, excluded from every channel | Excluded from all channels and auto-discovery |
The hve-core-all Superset section should clarify that items marked `maturity: removed` are **excluded entirely** (not retained in the superset for visibility like experimental/deprecated items).
**Steps to Reproduce**
See commit `19adc30` which:
- Updated `scripts/linting/schemas/collection-manifest.schema.json` to add `removed` to the `maturity` enum
- Marked `.github/skills/security/owasp-docker` as `maturity: removed` in `collections/security.collection.yml`
`docs/architecture/ai-artifacts.md` already documents the `removed` tier correctly (lines 319 and 360).
**Additional Context**
- File to update: `docs/customization/collections.md` (Maturity Filtering section, ~line 92, and hve-core-all Superset section, ~line 175)
- Reference: `docs/architecture/ai-artifacts.md` already has the correct five-tier table for consistency
- Schema source: `scripts/linting/schemas/collection-manifest.schema.json`
> Generated by [Documentation Update Check](https://github.com/microsoft/hve-core/actions/runs/24917128493/agentic_workflow) · ● 1.9M · [◷](https://github.com/search?q=repo%3Amicrosoft%2Fhve-core+is%3Aissue+%22gh-aw-workflow-call-id%3A+microsoft%2Fhve-core%2Fdoc-update-check%22&type=issues)
Contributor guide
Research direction
Start with docs/customization/collections.md, especially the Maturity Filtering section and hve-core-all Superset section. Compare them with the five-tier guidance in docs/architecture/ai-artifacts.md and the enum in scripts/linting/schemas/collection-manifest.schema.json. Done means both sections accurately explain the removed tier and its exclusion from all channels and auto-discovery.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100