fix(scripts): extend hve-core linter freshness (#1391)

This PR extends the repository's weekly hve-core freshness check to
cover two vendored PowerShell security linters.

## Problem and Context

Issue #1133 documents a blind spot in the existing freshness check. The
check covered hve-core-derived PowerShell modules by comparing the
upstream blob at the repository's pinned hve-core release commit with
the blob in the newest release, but it did not cover
`Test-WorkflowPermissions.ps1` or `Test-DangerousWorkflow.ps1`.

Those linters cannot use one global release baseline. Their local
headers identify different reviewed upstream commits, and at least one
upstream source is available on `main` but not in a release. The local
files also contain intentional adaptations, so comparing local file
contents directly with upstream would report expected differences as
drift.

## Proposed Solution

The documented design uses two baseline types in one manifest:

| Baseline | Files | Comparison |
|----------|-------|------------|
| `release` | Existing derived modules | Upstream blob at the RPI
bootstrap's pinned `UPSTREAM_REF` versus the same path at the resolved
newest non-draft release commit |
| `source-header` | Vendored security linters | Upstream blob at the
exact commit recorded in the local file's provenance header versus the
same path at one resolved upstream `main` commit |

Both modes compare upstream blobs with upstream blobs. This is the
principal mechanism for excluding intentional local adaptations from the
drift signal.

The script distinguishes upstream drift from invalid local provenance.
Drift remains an issue-triaged signal with a successful process exit;
local validation errors produce exit code 2. The workflow receives
separate attention, drift, and error counters.

## Logical Changed Blocks

### Freshness manifest and provenance parsing

`scripts/security/Test-HveCoreFreshness.ps1` changes the derived-file
manifest from a path list to entries containing `Path` and `Baseline`.
It adds both security linters as `source-header` entries.

`Get-HveCoreFileSource` reads only the comment-based help header and
requires one exact provenance statement containing the hve-core path and
a full 40-character commit SHA. The recorded upstream path must match
the local manifest path exactly. These constraints prevent malformed or
misleading provenance from selecting the wrong upstream object. The two
linter headers remove their parenthesized dates because repository
comment policy prohibits temporal markers in code; the immutable commit
SHA remains the provenance identifier.

Issue #1133 requires a per-file source revision. The implementation
validates that revision and path before trusting them as comparison
inputs.

### Immutable upstream resolution and drift classification

The check resolves the latest non-draft release tag and upstream `main`
to immutable full commit SHAs once per run. It validates the pinned
release ref before checking individual files. Each manifest entry is
dispatched to its baseline-specific comparison.

The drift model now distinguishes current, changed, missing-at-baseline,
missing-at-target, missing-at-both, and local validation-error states. A
missing path at both refs is treated as invalid configuration. A missing
source-header path at its recorded commit is also treated as invalid
provenance.

Documented rationale: the PR description says each run should use one
immutable release commit and one immutable `main` commit, and should
separate upstream drift from local validation errors.

### GitHub API and rendering boundaries

GitHub API helpers validate returned commit and blob SHAs. API failures
other than a reported HTTP 404 throw instead of appearing as missing
files. This prevents transient or malformed API responses from creating
false drift issues. Release URLs are restricted to HTTPS URLs on
`github.com`, and external text is encoded before insertion into
Markdown tables and labels so API-controlled values cannot alter
generated issue or job-summary structure. The helper contracts, failure
messages, and focused tests make these trust-boundary requirements
explicit.

### Results, process status, and workflow outputs

The JSON result gains the resolved release and `main` SHAs plus
independent `DriftCount` and `ErrorCount` values. The script emits
`attention-count`, `drift-count`, and `error-count` to GitHub Actions.
Drift alone exits successfully; validation errors exit with code 2.

The workflow opens or updates a tracking issue whenever attention is
required, uses separate drift and error counts in its title and comment,
and closes the issue only when neither exists. It checks the exit status
after editing an existing issue before adding the weekly comment.

Documented rationale: the PR description defines drift as issue-triaged
and invalid local provenance as workflow-failing. The issue itself asks
only that drift be surfaced; the exact failure policy is a design choice
recorded in this branch and its PR description.

### Reports and documentation

Issue and job-summary tables identify each file's baseline type, exact
upstream comparison, blob SHAs, state, and validation error. Refresh
guidance tells maintainers to review upstream changes, preserve local
adaptations, and update a source-header commit after review.

`scripts/README.md` documents both baseline modes and the required
source-header syntax. `.github/copilot-instructions.md` records the same
maintenance convention for future coding agents.

### Test expansion

`scripts/tests/security/Test-HveCoreFreshness.Tests.ps1` expands
coverage across the complete manifest, provenance parsing, release
selection, API response validation, state classification, baseline
dispatch, Markdown rendering, orchestration, workflow-output consumers,
exit policy, and the configuration-preview entry point.

## Summary

- Compare release-baseline modules between the pinned `UPSTREAM_REF` and
one immutable resolved latest-release commit; compare source-header
security linters between their recorded source commit and one immutable
resolved upstream `main` commit.
- Report upstream drift and local validation errors separately in JSON,
workflow outputs, and job summaries.
- Keep upstream drift as an issue-triaged signal while failing the
workflow for invalid local provenance.
- Validate provenance paths, full commit SHAs, API responses, release
tags, release URLs, and Markdown rendering at trust boundaries.
- Enforce the script-to-workflow output contract and fail when
tracking-issue updates do not succeed.
- Expand Pester coverage for the complete manifest, API request shapes,
report formatting, orchestration, and workflow consumers.

## Validation

- Affected security Pester suites: 163 passed
- PSScriptAnalyzer: 4 changed PowerShell files, 0 errors, 0 warnings
- Runtime smoke tests: freshness preview, live comparison, malformed
provenance, clean scans, violations, and invalid paths
- `git diff --check`

Closes #1133

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: algattik

.github/copilot-instructions.md

@@ -338,6 +338,10 @@ The `Physical-AI RPI` umbrella (`.github/agents/physical-ai-rpi.agent.md`) and i
 
 See [docs/reference/copilot-artifacts.md](../docs/reference/copilot-artifacts.md) for the full umbrella/worker rationale.
 
+## hve-core Derived Files
+
+Follow the baseline conventions in [`scripts/README.md`](../scripts/README.md). `scripts/security/Test-HveCoreFreshness.ps1` compares source-header entries with a resolved upstream `main` commit and release entries with the RPI `UPSTREAM_REF` and a resolved latest non-draft release commit.
+
 ## Git Workflow
 
 Full specification in `.github/instructions/commit-message.instructions.md`.

.github/workflows/check-hve-core-freshness.yml

@@ -31,30 +31,35 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Check hve-core-derived files against latest release
+      - name: Check hve-core-derived files against reviewed upstream baselines
         id: check
         env:
           GH_TOKEN: ${{ github.token }}
         run: ./scripts/security/Test-HveCoreFreshness.ps1
 
       - name: Create or update tracking issue
-        if: steps.check.outputs.stale-count != '0'
+        if: "!cancelled() && steps.check.outputs.attention-count != '' && steps.check.outputs.attention-count != '0'"
         env:
           GH_TOKEN: ${{ github.token }}
-          STALE_COUNT: ${{ steps.check.outputs.stale-count }}
+          DRIFT_COUNT: ${{ steps.check.outputs.drift-count }}
+          ERROR_COUNT: ${{ steps.check.outputs.error-count }}
         run: |
           . ./scripts/security/Test-HveCoreFreshness.ps1
           $data = Get-Content 'hve-core-freshness-results.json' -Raw | ConvertFrom-Json
           $runUrl = "$env:GITHUB_SERVER_URL/$env:GITHUB_REPOSITORY/actions/runs/$env:GITHUB_RUN_ID"
           $checkDate = Get-Date -Format 'yyyy-MM-dd' -AsUTC
           $body = Format-HveCoreIssueBody -Result $data -RunUrl $runUrl -CheckDate $checkDate
-          $title = "security: hve-core upstream updates available ($env:STALE_COUNT stale)"
+          $title = "security: hve-core freshness needs attention ($env:DRIFT_COUNT drifted, $env:ERROR_COUNT check errors)"
           $existing = Get-HveCoreTrackingIssue
-          if ($existing) { gh issue edit $existing --title $title --body $body; gh issue comment $existing --body "🔄 Weekly scan: $env:STALE_COUNT item(s) stale as of $checkDate. [Workflow run]($runUrl)." }
+          if ($existing) {
+            gh issue edit $existing --title $title --body $body
+            if ($LASTEXITCODE -ne 0) { throw "Could not update hve-core freshness issue #$existing" }
+            gh issue comment $existing --body "🔄 Weekly scan: $env:DRIFT_COUNT drifted, $env:ERROR_COUNT check errors as of $checkDate. [Workflow run]($runUrl)."
+          }
           else { gh issue create --title $title --body $body --label "dependencies,automated,needs-triage" }
 
       - name: Close resolved tracking issue
-        if: steps.check.outputs.stale-count == '0'
+        if: steps.check.outputs.attention-count == '0'
         env:
           GH_TOKEN: ${{ github.token }}
         run: |

scripts/README.md

@@ -71,13 +71,15 @@ Security scanning and dependency management scripts.
 | `security/Test-DependencyPinning.ps1` | Validate dependency pinning compliance                                                        |
 | `security/Test-SHAStaleness.ps1`      | Check for outdated SHA pins                                                                   |
 | `security/Test-BinaryFreshness.ps1`   | Validate pinned binary hashes and Helm chart versions; emits SARIF for GitHub Security tab    |
-| `security/Test-HveCoreFreshness.ps1`  | Check hve-core-derived modules against the latest upstream release                            |
+| `security/Test-HveCoreFreshness.ps1`  | Check hve-core-derived files against their reviewed release or source-header baselines        |
 | `security/zap-to-sarif.py`            | Convert ZAP results to SARIF format                                                           |
 | `update-chart-hashes.sh`              | Refresh pinned Helm chart versions and SHA-256 hashes in `infrastructure/setup/defaults.conf` |
 
 The `Test-BinaryFreshness.ps1` script is invoked by the `check-binary-integrity.yml` workflow on a weekly schedule. It downloads each pinned GPG key, installer, and CLI archive, compares SHA-256 hashes against the values pinned in `.devcontainer/install-dev-deps.sh` and `.devcontainer/devcontainer.json`, and queries upstream Helm repositories for chart version drift. Findings are written to `binary-freshness-results.sarif` with per-rule `helpUri` values pointing at the appropriate remediation script.
 
-The `Test-HveCoreFreshness.ps1` script is invoked by the `check-hve-core-freshness.yml` workflow on a weekly schedule. For every hve-core-derived module, it compares the **upstream** blob SHA at the pinned `UPSTREAM_REF` (the last reviewed upstream ref) against the newest non-draft `microsoft/hve-core` release. Comparing blobs, not release tags, means a stale signal is a real upstream change rather than an unrelated prerelease.
+The `Test-HveCoreFreshness.ps1` script is invoked by the `check-hve-core-freshness.yml` workflow on a weekly schedule. Each derived file declares a baseline. `release` files compare the **upstream** blob SHA at the pinned `UPSTREAM_REF` against one resolved, immutable newest non-draft release revision. `source-header` files compare the revision recorded in their header against one resolved, immutable upstream `main` revision. This reports relevant upstream changes before they appear in a release.
+
+Source-header files must include `Adapted from microsoft/hve-core <upstream-path> as of commit <40-hex SHA>`. Comparing upstream blobs avoids false drift from intentional local adaptations.
 
 ### 🔗 Where Pins Live
 

scripts/security/Test-DangerousWorkflow.ps1

@@ -18,7 +18,7 @@
       the pull-request head ref, executing untrusted code in a privileged context.
 
     Adapted from microsoft/hve-core scripts/security/Test-DangerousWorkflow.ps1
-    as of commit b70237d08d5caf6918b9de9952a243a8588b92dc (2026-07-02).
+    as of commit b70237d08d5caf6918b9de9952a243a8588b92dc.
 
     Local divergences from upstream (each marked inline with a '# LOCAL' comment):