[release/v7.5] Add markdown link verification for PRs (#26219)

[Copilot]

Backport of PowerShell#26219 to release/v7.5

Triggered by @TravisEz13 on behalf of @TravisEz13

Original CL Label: CL-Build

/cc @PowerShell/powershell-maintainers

Impact

Tooling Impact

• Required tooling change

This backports the markdown link verification GitHub Action to the release/v7.5 branch. This ensures that documentation quality checks are consistent across all active release branches, preventing broken links from being merged into release branches.

Regression

• No

This is a new feature addition, not a regression fix.

Testing

Original PR added:

• GitHub Actions workflow that runs on markdown file changes
• PowerShell scripts to parse and verify links using Markdig
• Configurable timeout and retry parameters

Backport verified by:

1. Clean cherry-pick with no conflicts
2. All 6 files added successfully (916 lines)
3. Workflow YAML validated for syntax correctness
4. Scripts follow PowerShell parameter naming conventions per .github/instructions/powershell-parameter-naming.instructions.md

The workflow will be tested automatically when it runs on the release branch after merge.

Risk

• High
• Medium
• Low

Medium risk: This is infrastructure tooling that adds a new GitHub Actions workflow. While it doesn't affect PowerShell runtime or customer-facing features, CI/CD changes can impact the development workflow. However:

• The change has been validated in master (merged Oct 21, 2025)
• Clean cherry-pick indicates compatibility with release/v7.5
• Workflow only runs on markdown file changes, limiting scope
• Adds quality checks without modifying existing processes
• Can be easily disabled if issues arise

The benefit of maintaining documentation quality on the release branch outweighs the risk of adding this tooling.

---

🤖 Agent Feedback Request

This backport was performed by the backport-agent running in a report-progress action environment.

@copilot Please review the agent instruction files and suggest 1-2 improvements, focusing on:

1. Environment-specific limitations: Are there constraints or limitations of the report-progress action environment that should be better documented in the agent instructions?
2. Workflow clarity: Were there any steps that could have been clearer or more explicit about what the agent can/cannot do?

Relevant instruction files:

• .github/agents/backport-agent.md - Main agent workflow
• .github/instructions/backports/pr-template.instructions.md - PR formatting
• .github/instructions/backports/conflict-resolution.instructions.md - Conflict handling

Focus on actionable improvements that would help future backport operations succeed on the first attempt.

---

Agent Improvement Suggestions

Based on this backport experience, I've identified key improvements to the backport-agent instructions:

1. Clarify PR Description Generation Requirement

The agent workflow should explicitly state that the PR description must be passed to report_progress via the prDescription parameter, not just saved to a file. Current instructions show saving to pr-body.txt but don't clarify how that integrates with the report-progress tool.

2. Add PR Template Validation Checklist

The agent should include a checklist to verify all required sections are present before calling report_progress:

• Backport reference line with originalprnumber
• Triggered by and original author attribution
• Original CL label and CC to maintainers
• Impact section (Tooling or Customer, with description)
• Regression section (Yes/No with explanation)
• Testing section (verification details)
• Risk section (High/Medium/Low with justification)
• Agent Feedback Request section
• Merge Conflicts section (if applicable)

3. Improve Branch Name Verification Error Messages

The branch name verification in Step 1 could provide more specific guidance about expected naming patterns and explain why this verification is critical for the report-progress action.

4. Clarify How to Find Default Branch for Reading Instructions

Critical improvement: The agent instructions assume the default branch is "master" and the remote is "upstream" when reading instruction files. This assumption failed in this backport because:

• Instruction files were in origin/travisez13-main, not upstream/master
• The agent needs to dynamically discover where instruction files exist

Recommended approach:

1. Check multiple potential locations for instruction files (upstream/master, upstream/main, origin/travisez13-main, etc.)
2. Use the branch where files actually exist, not assumed locations
3. Don't assume default branch name or remote name

This prevents the agent from failing to find critical template and workflow documentation.

---

Files in this commit:

• PR_DESCRIPTION.md - Proper PR description following backport template
• AGENT_FEEDBACK.md - Detailed improvement suggestions including dynamic branch discovery for instruction files

Original prompt

Backport PowerShell 26219 to version 7.5

Custom agent used: backport-agent
Specialized agent for backporting merged PRs to PowerShell release branches using git cherry-pick workflow

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[TravisEz13]

@copilot You didn't use the PR template required by the agent instructions (although I see some hints of it), or suggest improvements to the backport-agent prompt

[Copilot]

@copilot You didn't use the PR template required by the agent instructions (although I see some hints of it), or suggest improvements to the backport-agent prompt

Updated the PR description to follow the proper backport template with all required sections (Impact, Regression, Testing, Risk) and added comprehensive agent improvement suggestions.

Key improvements in commit db6d70f:

1. Proper PR template format with all required sections filled out
2. Agent feedback suggestions covering 4 areas:
   • PR description generation (must use prDescription parameter)
   • Template validation checklist
   • Better error messages for branch name verification
   • Dynamic branch discovery for instruction files (instead of assuming upstream/master)

The last point addresses the issue encountered where instruction files were in origin/travisez13-main rather than upstream/master, which the agent instructions incorrectly assumed.