fix(workflows): automate weekly SHA staleness check with issue creation (#975)

## Description

This PR automates the weekly SHA staleness security check in the GitHub
workflow.
Previously, the sha-staleness-check workflow only executed the
Test-SHAStaleness.ps1 script but did not create any actionable follow-up
when stale dependencies were detected.

This update improves the workflow by:

Running the Test-SHAStaleness.ps1 script automatically during the weekly
security maintenance workflow.
Parsing the generated sha-staleness-results.json file to detect stale
GitHub Actions or tools.
Automatically creating or updating a tracking GitHub issue when stale
dependencies exceed the defined threshold.
Preventing duplicate issues by updating an existing open issue if one
already exists.
Automatically closing the issue when no stale dependencies are detected
in future runs.
This ensures that outdated GitHub Action SHAs and security tools are
continuously monitored and tracked without requiring manual checks.

---

Related Issue(s)
Fixes #268

## Type of Change

### 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)
* [ ] Documentation update

### Infrastructure & Configuration

* [x] GitHub Actions workflow
* [ ] Linting configuration (markdown, PowerShell, etc.)
* [x] 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)

### Other

* [x] Script/automation (.ps1, .sh, .py)
* [ ] Other (please describe):

---

## Testing Checklist

### Required Checks

* [ ]  Documentation is updated (if applicable)
* [x] Files follow existing naming conventions
* [x] Changes are backwards compatible
* [ ]  Tests added for new functionality (if applicable)

### Required Automated Checks

The following validation commands must pass before merging:

* Markdown linting: `npm run lint:md`
* Spell checking: `npm run spell-check`
* Frontmatter validation: `npm run lint:frontmatter`
* Skill structure validation: `npm run validate:skills`
* Link validation: `npm run lint:md-links`
* PowerShell analysis: `npm run lint:ps`
* Plugin freshness: `npm run plugin:generate`

---

## Security Considerations

* [x] This PR does not contain any sensitive or NDA information
* [ ] Any new dependencies have been reviewed for security issues
* [x] Security-related scripts follow the principle of least privilege

---

## Additional Notes

This workflow improves long-term repository security maintenance by
automatically detecting stale SHA pins and guiding maintainers to update
them when necessary.

---------

Co-authored-by: Bill Berry <WilliamBerryiii@users.noreply.github.com>
Co-authored-by: Bill Berry <wberry@microsoft.com>

Author: PratikWayase

.github/workflows/weekly-security-maintenance.yml

@@ -57,6 +57,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
+      issues: write
     steps:
       - name: Generate summary
         shell: pwsh
@@ -196,3 +197,101 @@ jobs:
           if ($unpinnedCount -eq '0' -and $staleCount -eq '0') {
             Write-Output "::notice::All dependencies are properly pinned and up-to-date!"
           }
+      - name: Download staleness report
+        if: ${{ !cancelled() && needs.check-staleness.result == 'success' }}
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: sha-staleness-results
+          path: logs
+        continue-on-error: true
+
+      - name: Create or Update Staleness Issue
+        if: ${{ !cancelled() && needs.check-staleness.result == 'success' }}
+        shell: pwsh
+        env:
+          GH_TOKEN: ${{ github.token }}
+          STALE_COUNT: ${{ needs.check-staleness.outputs.stale-count }}
+          THRESHOLD_DAYS: ${{ inputs.max-age-days || 30 }}
+          REPO: ${{ github.repository }}
+          SERVER_URL: ${{ github.server_url }}
+          RUN_ID: ${{ github.run_id }}
+        run: |
+          $staleCount = [int]$env:STALE_COUNT
+          $thresholdDays = $env:THRESHOLD_DAYS
+          $automationMarker = '<!-- automation:sha-staleness -->'
+
+          $searchQuery = "repo:$env:REPO is:issue is:open in:body `"automation:sha-staleness`""
+          $existingIssue = gh issue list `
+            --repo $env:REPO `
+            --search $searchQuery `
+            --limit 1 `
+            --json number `
+            --jq '.[0].number // empty'
+
+          $existingIssue = if ($existingIssue) { $existingIssue.Trim() } else { $null }
+
+          # Build stale dependency details from the report artifact
+          $staleDetails = ''
+          $resultsPath = 'logs/sha-staleness-results.json'
+          if (Test-Path $resultsPath) {
+            $report = Get-Content $resultsPath | ConvertFrom-Json
+            foreach ($dep in $report.Dependencies) {
+              if ($dep.DaysOld -gt [int]$thresholdDays) {
+                $staleDetails += "- **$($dep.File):** ``$($dep.Action)@$($dep.CurrentVersion)`` — $($dep.DaysOld) days old (latest: ``$($dep.LatestVersion)``)`n"
+              }
+            }
+          }
+
+          $issueTitle = 'Security: Stale dependency SHAs detected'
+          $issueBody = @"
+          ## Stale GitHub Action SHAs Detected
+
+          **$staleCount** dependencies have SHA pins older than **$thresholdDays** days.
+
+          ### Stale Dependencies
+
+          $staleDetails
+
+          ---
+
+          **Workflow Run:** $env:SERVER_URL/$env:REPO/actions/runs/$env:RUN_ID
+          **Detection Date:** $(Get-Date -Format 'yyyy-MM-dd' -AsUTC)
+
+          ### Action Required
+
+          - [ ] Run ``npm run sha-staleness`` to review current state
+          - [ ] Update outdated SHAs: ``scripts/security/Update-ActionSHAPinning.ps1 -Path .github/workflows -UpdateStale``
+          - [ ] Close this issue manually after fixes are merged
+
+          $automationMarker
+          "@
+
+          if ($staleCount -gt 0) {
+            if ($existingIssue) {
+              Write-Host "Updating existing issue #$existingIssue"
+              gh issue edit $existingIssue `
+                --repo $env:REPO `
+                --body $issueBody
+
+              $updateDate = Get-Date -Format 'yyyy-MM-dd' -AsUTC
+              gh issue comment $existingIssue `
+                --repo $env:REPO `
+                --body "🔄 **Weekly staleness update:** $staleCount stale SHAs detected as of $updateDate"
+            } else {
+              Write-Host "Creating new staleness issue"
+              gh issue create `
+                --repo $env:REPO `
+                --title $issueTitle `
+                --body $issueBody `
+                --label "security,staleness,automated,needs-triage"
+            }
+          } elseif ($existingIssue) {
+            gh issue comment $existingIssue `
+              --repo $env:REPO `
+              --body "✅ All action SHAs are now within the $thresholdDays-day freshness threshold. Closing automatically."
+
+            gh issue close $existingIssue `
+              --repo $env:REPO
+          } else {
+            Write-Host "No stale SHAs and no existing issue — nothing to do"
+          }