Skip to content

Commit c2b806f

Browse files
rezatnoMsirhCrezatnoMsirhC
authored
chore(docs): correct New-MsDateReport table rendering and refresh stale docs (#1114)
# chore(docs): correct New-MsDateReport table rendering and refresh stale docs ## Description This PR fixes a bug in `Invoke-MsDateFreshnessCheck.ps1` that caused merged table rows in GitHub Actions step summaries, refreshes ms.date frontmatter on thirteen stale documentation files, and documents previously undocumented scripts, modules, and workflows across three scripts READMEs. A separate correction to `docs/contributing/prompts.md` aligns the frontmatter field documentation with actual prompt file practice in the repository. ### Bug Fix — `New-MsDateReport` table rendering `New-MsDateReport` builds a markdown table using a PowerShell here-string. The here-string terminator `"@` consumed the trailing newline of the separator row `|------|---------|------------|`, causing the first `foreach` data row to append directly onto the separator line. In GitHub Actions step summaries this produced merged output like: ``` |------|---------|------------|| scripts/tests/Fixtures/Frontmatter/valid-docs.md | ... ``` Fix: insert `$markdown += "\`n"` immediately after the `"@` closing of the header here-string. ### Documentation — `docs/contributing/prompts.md` The frontmatter fields section was out of sync with actual `.prompt.md` files in the repository: - `mode` was documented as MANDATORY but is absent from all prompt files; moved to Optional Fields. - `category` was listed as optional but is not used in any prompt file or standard; removed. - Four new optional fields documented: `agent`, `argument-hint`, `model`, `disable-model-invocation`. - New Input Variables section: `${input:varName:defaultValue}` syntax. - New Activation Lines section: `---` separator as the workflow entry point pattern. - Frontmatter example updated to match corrected field set. ### Documentation — Scripts READMEs `scripts/linting/README.md`: Added documentation for three previously undocumented scripts (`Invoke-MsDateFreshnessCheck.ps1`, `Invoke-PythonLint.ps1`, `Invoke-PythonTests.ps1`), the `Modules/FrontmatterValidation.psm1` module with its three exported classes, and five workflow rows (`msdate-freshness-check.yml`, `python-lint.yml`, `pytest-tests.yml`, `copyright-headers.yml`, `skill-validation.yml`). `scripts/security/README.md`: Added documentation for two previously undocumented scripts (`Invoke-PipAudit.ps1`, `Test-WorkflowPermissions.ps1`) and two workflow rows (`pip-audit.yml`, `workflow-permissions-scan.yml`). `scripts/README.md`: Added three rows to the Linting Scripts cross-reference table. ### ms.date Refreshes Updated `ms.date` to `2026-03-17` on thirteen files that exceeded the staleness threshold. No content changes to those files beyond the date field. ## Related Issue(s) | Issue(s) | Files Affected | Resolution Method | |---|---|---| | #1113 | `scripts/linting/Invoke-MsDateFreshnessCheck.ps1` | Bug fix: inserted missing newline after table header here-string in `New-MsDateReport` | | #1061 | `docs/contributing/instructions.md` | ms.date update | | #1062 | `docs/contributing/prompts.md` | Content update: corrected frontmatter field documentation | | #1063, #1064, #1065, #1066, #1067, #1068, #1069, #1070, #1071, #1072, #1073, #1074 | `docs/templates/adr-template-solutions.md` (canonical); plugin copies resolved via symlink | ms.date update on canonical file; symlinks propagate to all 11 plugin copies | | #1075, #1076, #1077, #1078, #1079, #1080, #1081, #1082, #1083, #1084, #1085, #1087 | `scripts/lib/README.md` (canonical); plugin copies resolved via symlink | ms.date update on canonical file; symlinks propagate to all 11 plugin copies | | #1086 | `scripts/extension/README.md` | ms.date update | | #1088 | `scripts/linting/README.md` | Content update + ms.date: added 3 scripts, 1 module, 5 workflow rows | | #1089 | `scripts/security/README.md` | Content update + ms.date: added 2 scripts, 2 workflow rows | | #1090 | `scripts/tests/Fixtures/Frontmatter/valid-docs.md` | ms.date update | | #1091 | `scripts/tests/README.md` | ms.date update | | #1092 | `scripts/README.md` | Content update + ms.date: added 3 linting script rows | | #1093 | `CODE_OF_CONDUCT.md` | ms.date update | | #1094 | `SUPPORT.md` | ms.date update | ## Type of Change Select all that apply: **Code & Documentation:** * [x] 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) * [x] Documentation update **Infrastructure & Configuration:** * [ ] GitHub Actions workflow * [ ] Linting configuration (markdown, PowerShell, etc.) * [ ] Security configuration * [ ] DevContainer configuration * [ ] Dependency update **AI Artifacts:** * [ ] Reviewed contribution with `prompt-builder` agent and addressed all feedback * [ ] Copilot instructions (`.github/instructions/*.instructions.md`) * [ ] Copilot prompt (`.github/prompts/*.prompt.md`) * [ ] Copilot agent (`.github/agents/*.agent.md`) * [ ] Copilot skill (`.github/skills/*/SKILL.md`) > 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](../docs/contributing/skills.md). > * Model Versions: Only contributions targeting the **latest Anthropic and OpenAI models** will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected. > * See [Agents Not Accepted](../docs/contributing/custom-agents.md#agents-not-accepted) and [Model Version Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements). **Other:** * [x] Script/automation (`.ps1`, `.sh`, `.py`) * [ ] Other (please describe): ## Testing The bug fix was validated by running the full Pester test suite (1841 tests; 0 failures) and PSScriptAnalyzer (0 violations). Documentation changes were validated via markdownlint (0 errors), spell check (0 issues), frontmatter validation (0 errors), and link validation (0 errors). No behavioral changes to scripts other than the one-line insertion in `New-MsDateReport`. ## Checklist ### Required Checks * [x] Documentation is updated (if applicable) * [x] Files follow existing naming conventions * [x] Changes are backwards compatible (if applicable) * [ ] Tests added for new functionality (if applicable) ### AI Artifact Contributions <!-- If contributing an agent, prompt, instruction, or skill, complete these checks --> * [ ] Used `/prompt-analyze` to review contribution * [ ] Addressed all feedback from `prompt-builder` review * [ ] Verified contribution follows common standards and type-specific requirements ### Required Automated Checks The following validation commands must pass before merging: * [x] Markdown linting: `npm run lint:md` — 0 errors (161 files) * [x] Spell checking: `npm run spell-check` — 0 issues (255 files) * [x] Frontmatter validation: `npm run lint:frontmatter` — 0 errors, 0 warnings * [x] Skill structure validation: `npm run validate:skills` — 0 errors, 0 warnings (5 skills) * [x] Link validation: `npm run lint:md-links` — passed * [x] PowerShell analysis: `npm run lint:ps` — 0 violations * [x] Plugin freshness: `npm run plugin:generate` — no changes (0 errors) ## Security Considerations * [x] This PR does not contain any sensitive or NDA information * [x] Any new dependencies have been reviewed for security issues * [x] Security-related scripts follow the principle of least privilege ## Additional Notes No AI artifact files were modified. No workflow files were changed. No dependency changes. The `plugin:generate` run produced no output changes, confirming collection manifests are unaffected.
1 parent cb1fd05 commit c2b806f

File tree

13 files changed

+339
-43
lines changed

13 files changed

+339
-43
lines changed

‎CODE_OF_CONDUCT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Code of Conduct
33
description: Microsoft Open Source Code of Conduct and community behavior expectations
44
author: Microsoft Open Source Programs Office
5-
ms.date: 2025-11-04
5+
ms.date: 2026-03-17
66
ms.topic: reference
77
keywords:
88
- code of conduct

‎SUPPORT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Support
33
description: Community support commitments, response times, and escalation paths for the HVE Core project
44
author: HVE Core Team
5-
ms.date: 2025-11-05
5+
ms.date: 2026-03-17
66
ms.topic: reference
77
keywords:
88
- support

‎docs/contributing/instructions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: 'Contributing Instructions to HVE Core'
33
description: 'Requirements and standards for contributing GitHub Copilot instruction files to hve-core'
44
sidebar_position: 3
55
author: Microsoft
6-
ms.date: 2025-11-26
6+
ms.date: 2026-03-17
77
ms.topic: how-to
88
---
99

‎docs/contributing/prompts.md‎

Lines changed: 101 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: 'Contributing Prompts to HVE Core'
33
description: 'Requirements and standards for contributing GitHub Copilot prompt files to hve-core'
44
sidebar_position: 4
55
author: Microsoft
6-
ms.date: 2025-11-26
6+
ms.date: 2026-03-17
77
ms.topic: how-to
88
---
99

@@ -69,59 +69,134 @@ Prompt files MUST:
6969
| Style | Sentence case with proper punctuation |
7070
| Example | `'Required protocol for creating Azure DevOps pull requests with work item discovery and reviewer identification'` |
7171

72-
**`mode`** (string enum, MANDATORY for prompts)
72+
### Optional Fields
7373

74-
| Property | Value |
75-
|----------|----------------------------------------|
76-
| Purpose | Defines when/how the prompt is invoked |
77-
| Example | `workflow` |
74+
**`agent`** (string)
7875

79-
Valid values:
76+
| Property | Value |
77+
|----------|--------------------------------------------------------------------------|
78+
| Purpose | Delegates execution to a named custom agent |
79+
| Format | Human-readable agent name matching the agent's `name:` frontmatter field |
80+
| Style | Quote the value when the agent name contains spaces |
81+
| Example | `'ADO Backlog Manager'` |
8082

81-
* `agent` - Used by specialized AI agents
82-
* `assistant` - General-purpose assistance context
83-
* `copilot` - GitHub Copilot-specific workflows
84-
* `workflow` - Automated workflow/pipeline context
83+
**`argument-hint`** (string)
8584

86-
### Optional Fields
85+
| Property | Value |
86+
|----------|------------------------------------------------------------------------------------------------------------------------------------------------|
87+
| Purpose | Displays expected inputs in the VS Code prompt picker |
88+
| Format | Brief string; required arguments first, then optional; `[]` for positional, `key=value` for named, `{option1\|option2}` for enumerated choices |
89+
| Style | Keep hints concise; lead with required arguments |
90+
| Example | `"project=... [type={Epic\|Feature\|UserStory\|Bug\|Task}] [title=...]"` |
91+
92+
**`model`** (string)
93+
94+
| Property | Value |
95+
|----------|-----------------------------------------------------------------------------------|
96+
| Purpose | Specifies a preferred AI model for prompt invocation |
97+
| Format | Model identifier string |
98+
| Style | Use the model's canonical identifier; omit if the workspace default is acceptable |
99+
| Example | `gpt-4o` |
87100

88-
**`category`** (string enum)
101+
**`disable-model-invocation`** (boolean)
89102

90-
Organizes prompts by domain.
103+
| Property | Value |
104+
|----------|---------------------------------------------------------------------------------------|
105+
| Purpose | Prevents the prompt from automatically invoking an AI model at start |
106+
| Format | Boolean (`true` or `false`) |
107+
| Style | Use for prompts that gather context or run setup steps before handing off to the user |
108+
| Example | `true` |
91109

92-
Valid values:
110+
**`mode`** (string)
93111

94-
* `ado` - Azure DevOps workflows
95-
* `git` - Git operations
96-
* `documentation` - Documentation generation/maintenance
97-
* `workflow` - General workflow automation
98-
* `development` - Development tasks
112+
| Property | Value |
113+
|----------|------------------------------------------------------------------------------|
114+
| Purpose | Specifies the invocation context |
115+
| Format | Enumerated string; valid values: `agent`, `assistant`, `copilot`, `workflow` |
116+
| Style | Lowercase |
117+
| Example | `agent` |
118+
119+
**`category`** (string)
120+
121+
| Property | Value |
122+
|----------|------------------------------------------------------------------|
123+
| Purpose | Groups the prompt by topic or domain for organizational purposes |
124+
| Format | String identifying the domain or topic area |
125+
| Style | Lowercase kebab-case (e.g., `code-review`, `ado`, `git`) |
126+
| Example | `code-review` |
99127

100128
**`version`** (string)
101129

102-
Tracks prompt revisions using semantic versioning (e.g., `1.0.0`).
130+
| Property | Value |
131+
|----------|------------------------------------------------|
132+
| Purpose | Tracks prompt revisions |
133+
| Format | Semantic versioning string (MAJOR.MINOR.PATCH) |
134+
| Style | Quoted string |
135+
| Example | `'1.0.0'` |
103136

104137
**`author`** (string)
105138

106-
Attribution for the prompt creator (e.g., `microsoft/hve-core`, `your-team-name`).
139+
| Property | Value |
140+
|----------|--------------------------------------|
141+
| Purpose | Attribution for the prompt creator |
142+
| Format | Team or repository identifier string |
143+
| Style | Use `org/repo` format or a team name |
144+
| Example | `'microsoft/hve-core'` |
107145

108146
**`lastUpdated`** (string)
109147

110-
Timestamp of last modification in ISO 8601 format (YYYY-MM-DD).
148+
| Property | Value |
149+
|----------|-----------------------------------|
150+
| Purpose | Timestamp of last modification |
151+
| Format | ISO 8601 date string (YYYY-MM-DD) |
152+
| Style | Quoted string |
153+
| Example | `'2026-03-17'` |
111154

112155
### Frontmatter Example
113156

114157
```yaml
115158
---
116159
description: 'Required protocol for creating Azure DevOps pull requests with work item discovery, reviewer identification, and automated linking'
117-
mode: 'workflow'
118-
category: 'ado'
160+
agent: 'ADO Backlog Manager'
161+
argument-hint: "project-slug=... [type={PR|Draft}]"
119162
version: '1.0.0'
120163
author: 'microsoft/hve-core'
121-
lastUpdated: '2025-11-19'
164+
lastUpdated: '2026-03-17'
122165
---
123166
```
124167

168+
### Input Variables
169+
170+
Prompts can declare input variables that VS Code resolves at invocation time. The syntax is:
171+
172+
```text
173+
${input:varName}
174+
${input:varName:defaultValue}
175+
```
176+
177+
Declare variables in an Inputs section and reference them in prompt content:
178+
179+
```markdown
180+
## Inputs
181+
182+
* ${input:topic}: (Required) Primary topic or focus area.
183+
* ${input:scope:all}: (Optional, defaults to all) Scope of the operation.
184+
```
185+
186+
Required inputs (no default) are inferred from the user's conversation or attached files when not explicitly supplied.
187+
188+
### Activation Lines
189+
190+
Prompts that need to clarify the workflow entry point can include an activation line: a `---` separator followed by an instruction that tells the agent where to begin. Activation lines apply only to prompt files and are omitted when the delegated agent's phases already define the workflow start.
191+
192+
```markdown
193+
---
194+
195+
Begin by reading the current branch state and identifying open work items.
196+
```
197+
198+
Prompts that delegate to a custom agent via `agent:` typically omit the activation line because the agent's phases define execution order.
199+
125200
## Collection Entry Requirements
126201

127202
All prompts must have matching entries in one or more `collections/*.collection.yml` manifests. Collection entries control distribution and maturity.
@@ -352,7 +427,6 @@ When specific files/paths trigger behavior:
352427
```yaml
353428
---
354429
description: 'Required protocol for creating Azure DevOps pull requests'
355-
mode: 'workflow'
356430
applyTo: '**/.copilot-tracking/pr/new/**' # Workflow-specific context
357431
---
358432
```

‎docs/templates/adr-template-solutions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: ADR Title
33
description: '[The title should be unique within the library, provide a longer title if needed to differentiate with other ADRs]'
44
sidebar_position: 1
55
author: Name of author(s)
6-
ms.date: 2025-06-06
6+
ms.date: 2026-03-17
77
ms.topic: architecture
88
estimated_reading_time: 2
99
keywords:

‎scripts/README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Scripts
33
description: PowerShell scripts for linting, validation, and security automation
44
author: HVE Core Team
5-
ms.date: 2025-11-05
5+
ms.date: 2026-03-17
66
ms.topic: reference
77
keywords:
88
- powershell
@@ -59,6 +59,9 @@ The `linting/` directory contains scripts for validating code quality and docume
5959
| `Markdown-Link-Check.ps1` | Validate markdown links |
6060
| `Invoke-YamlLint.ps1` | YAML file validation |
6161
| `Test-CopyrightHeaders.ps1` | Validate copyright headers in source files |
62+
| `Invoke-MsDateFreshnessCheck.ps1` | Check ms.date frontmatter freshness |
63+
| `Invoke-PythonLint.ps1` | Python linting via ruff |
64+
| `Invoke-PythonTests.ps1` | Python tests via pytest |
6265

6366
See [linting/README.md](linting/README.md) for detailed documentation.
6467

‎scripts/extension/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Extension Scripts
33
description: PowerShell scripts for VS Code extension preparation, packaging, and collection discovery
44
author: HVE Core Team
5-
ms.date: 2025-11-05
5+
ms.date: 2026-03-17
66
ms.topic: reference
77
keywords:
88
- powershell

‎scripts/lib/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Shared Library
33
description: Shared utility scripts and modules used across hve-core automation
44
author: HVE Core Team
5-
ms.date: 2025-11-05
5+
ms.date: 2026-03-17
66
ms.topic: reference
77
keywords:
88
- powershell

‎scripts/linting/Invoke-MsDateFreshnessCheck.ps1‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -204,6 +204,7 @@ function New-MsDateReport {
204204
| File | ms.date | Age (days) |
205205
|------|---------|------------|
206206
"@
207+
$markdown += "`n"
207208

208209
$sortedStaleFiles = $staleFiles | Sort-Object -Property AgeDays -Descending
209210

0 commit comments

Comments
 (0)