[PM-04] Add framework integrity check to content-health workflow

[Copilot]

Adds a new advisory validator that enforces governance framework metadata headers on all repo scripts, wired into the weekly content-health workflow.

Description

Scripts across scoped roots (.githooks, .github/scripts, tests, tools/scripts, tasks/scripts) are required to carry a framework header schema (@script, @category, @purpose, @scope, @owner, @needs, @purpose-statement, @pipeline). Previously, no automated check ran against the full corpus — only staged additions were covered at commit time. This adds a scheduled advisory sweep for the whole repo.

Scope

In-scope:

• .github/workflows/content-health.yml — new step added
• tools/scripts/validators/structure/check-framework-integrity.js — new validator
• tools/script-index.md, docs-guide/indexes/scripts-index.mdx — index rebuild to include new script

Out-of-scope: no changes to existing validators, test logic, or header enforcement policies

Validation

# Validator runs clean against current repo
node tools/scripts/validators/structure/check-framework-integrity.js
# → ✅ Framework integrity check passed (188 scripts checked, all indexes current)

# --strict mode exits 1 on any issue; default is advisory (exit 0)
node tools/scripts/validators/structure/check-framework-integrity.js --strict

# Indexes rebuilt after adding new script
node tests/unit/script-docs.test.js --write --rebuild-indexes
# → ✅ Script documentation checks passed

# CodeQL: 0 alerts

Follow-up Tasks

none

Type of Change

• Bug fix (fixes an issue)
• New content (adds new documentation)
• Content update (improves existing content)
• Style/formatting fix
• Information architecture change
• Other (please describe)

Adds a new governance/repo-health validator and wires it into the scheduled content-health workflow.

Related Issues

Related to #

Changes Made

• tools/scripts/validators/structure/check-framework-integrity.js — new script; delegates to runTests({ enforceExisting: true, checkIndexes: true }) from tests/unit/script-docs.test.js; advisory by default (exit 0), --strict flips to exit 1; defensive guards on result shape with remediation hints in output
• .github/workflows/content-health.yml — appended Framework integrity check step with continue-on-error: true, matching the advisory posture of all other steps in this workflow
• Script indexes — rebuilt tools/script-index.md and docs-guide/indexes/scripts-index.mdx to register the new validator

Testing

• Tested locally with npm run dev
• Verified all links work
• Checked formatting and style
• Reviewed against style guides
• Screenshots (if UI changes)

Screenshots (if applicable)

N/A

Checklist

• My changes follow the style guides
• I've reviewed the Component Library for available components
• I've updated related pages if needed
• I've checked for broken links
• My changes are clear and easy to understand
• I've tested locally
• I've added/updated keywords and metadata if needed

Additional Notes

The new validator is intentionally advisory (continue-on-error: true) to match the existing content-health posture — findings surface in workflow logs without blocking. Use --strict if a blocking gate is desired in future.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[PM-04] Add framework integrity check to content-health workflow</issue_title>
<issue_description>Tracking issue for PM-04 in the Sprint 3 + Post-Migration Audit stream.

Scope:

• Implement Add framework integrity check to content-health workflow
• Keep changes isolated to the task branch/worktree
• Validate against docs-v2 governance rules before PR</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [PM-04] Add framework integrity check to content-health workflow #805

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.