microsoft / microsoft/hve-core

feat: add a hub-completeness guard to prevent instruction/prompt index README drift

Open
#2,435 0 comments 1 reaction 1 assignee Claimed by @jkim323 View on GitHub
agent-ready feature linting priority-3 scripts
Dominant language
Python
Stars
1.5k
Forks
301
Avg merge
3d 3h
Merged PRs (30d)
92

Description

## Issue Description

The two documentation hub indexes — `.github/instructions/README.md` (Available Instructions) and `.github/prompts/README.md` (Available Prompts) — are maintained by hand and drift silently. When a new `*.instructions.md` or `*.prompt.md` artifact is added (or renamed) without updating its index README, nothing fails, so the index quietly falls out of sync with the actual files on disk. This drift was recently discovered and reconciled manually, but there is no automated guard to keep the two hubs complete going forward.

These two READMEs are also outside the current `lint:md` coverage (the `.github/instructions/**` and `.github/prompts/**` globs are excluded), so markdownlint does not catch the gap either.

**Request:** Add a lightweight CI-style guard that fails when an instruction or prompt artifact is not referenced in its index README.

### Proposed design

- New validator: `scripts/linting/Test-DocHubCompleteness.ps1` (dot-sourceable core + CLI guard, matching the convention used by `scripts/linting/Test-ExtensionArtifactNaming.ps1`).
- Two hubs checked:
- `.github/instructions/README.md` ← `.github/instructions/**/*.instructions.md`
- `.github/prompts/README.md` ← `.github/prompts/**/*.prompt.md` (excludes `dt-method-*` per-method coaching prompts, which the hub intentionally summarizes in a note rather than linking individually)
- Matching strategy: assert each artifact's file name appears somewhere in its hub README (a directory-tree entry or an Available-* table link both embed the file name). Report any artifact whose name is absent, and exit `1`.
- Pester test: `scripts/tests/linting/Test-DocHubCompleteness.Tests.ps1` covering the complete-hub pass case, a missing-entry failure, and the `dt-method-*` exclusion.
- Add an npm script (for example `lint:doc-hubs`); wire into the `lint:all` chain only after confirmation, since that gates CI.

### Acceptance criteria

- [ ] Validator enumerates both hubs and fails on any unreferenced `*.instructions.md` / `*.prompt.md` artifact.
- [ ] `dt-method-*` prompts are excluded from the prompts hub check.
- [ ] Pester tests cover pass, missing-entry fail, and exclusion cases.
- [ ] npm script added; `lint:all` / CI wiring decided explicitly.
- [ ] Guard passes against the current repository state.

## Additional Context

A working prototype of this guard was built during the documentation refresh in PR #2434 and validated locally (passed against the repo with 144 artifacts referenced; 3/3 Pester tests passing; clean under the repo's PSScriptAnalyzer settings, which already exclude `PSAvoidUsingWriteHost` and `PSUseShouldProcessForStateChangingFunctions`). It was intentionally **not** included in #2434 to keep that PR scoped to documentation only — this tooling belongs in its own change. This issue captures the design so it can be picked up as a self-contained tooling PR.

Related duplicate-basename note: `pull-request.instructions.md` exists at both the instructions root and under `hve-core/`, which is a minor false-pass edge for pure basename matching and can be tightened if needed.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.