docs: fix linting scripts README and instruction file gaps (#1107)

[PratikWayase]

Description

This PR resolves documentation coverage gaps in the linting scripts and instruction files as outlined in Issue #1107. Specifically, it makes the following updates:

• scripts/linting/README.md: Added comprehensive documentation for the schemas/directory, listing all 10 JSON schema files and the schema-mapping.jsonmapping file.

• .github/copilot-instructions.md: Explicitly added lint:permissions and lint:dependency-pinning to the "Using npm Scripts" list to ensure they are documented as individual scripts, alongside their existing inclusion in the lint:all chain.

(Note: Documentation for missing scripts, modules, and the workflows table was already present in the repository, so this PR focuses strictly on the remaining gaps identified in the issue).

Related Issue(s)

Fixes #1107

Type of Change

Select all that apply:

Code & Documentation:

• 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:

• 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)

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Testing

Verified locally by running:

• npm run lint:md (Passed with 0 errors)
• npm run lint:frontmatter (Passed validation for all modified files)
• Searched the codebase to confirm validate:frontmatter no longer exists and the new schema documentation is correctly placed.

Checklist

Required Checks

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

AI Artifact Contributions

• 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

• 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
• Docusaurus tests: npm run docs:test

Security Considerations

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

Additional Notes

Pre-existing frontmatter validation errors in .github/skills/design-thinking/ (related to "Standard Copilot footer") are unrelated to the changes in this PR and were present before these documentation updates.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.62%. Comparing base (da9ffa2) to head (23890f9).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1948      +/-   ##
==========================================
- Coverage   80.63%   80.62%   -0.01%     
==========================================
  Files         117      117              
  Lines       19089    19089              
==========================================
- Hits        15392    15391       -1     
- Misses       3697     3698       +1     

Flag	Coverage Δ
pester	84.20% <ø> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[katriendg]

Hey @PratikWayase — thank you for picking this up! The changes to copilot-instructions.md look good, and the structure of the schemas section in the linting README is exactly what we needed.

Unfortunately this is on us: the issue itself was written when the schemas/ directory only had 10 files, but we've since added 9 more schema files. The directory now contains 19 JSON schemas total. I've updated the issue with the current list.

Would you be able to update the schemas section to include all 19? Happy to help if you'd like a list — just let me know!

[katriendg]

For reference, these are the 9 schemas that were added after the issue was filed and need to be included in the README section:

• accessibility-state.schema.json
• adr-config.schema.json
• adr-consistency-rules.schema.json
• adr-frontmatter.schema.json
• ai-artifact-config.schema.json
• model-catalog.schema.json
• rai-state.schema.json
• security-state.schema.json
• sssc-state.schema.json

Also a minor note: lint:permissions runs Test-WorkflowPermissions.ps1, so a description like "Workflow permissions validation" might be more precise than "File permission and mode validation" — but that's a small thing, up to you!

[katriendg]

Please see my comments around some missing content before we merge. Thank you!

[katriendg]

See the issue itself, it now has updated information about the full list to document here.

[bindsi]

Approved: the linting README and instruction updates are documentation-only and align with the current validation surface. I did not find actionable issues.

[bindsi]

Approved: the linting documentation updates align with the current validation surface. I did not find actionable issues in the current head.