fix(instructions): define CI configuration provenance

[Bill Berry (WilliamBerryiii)]

fix(instructions): define CI configuration provenance

Description

Updated the Bash authoring guidance so repository-managed CI configuration is treated as executable code whose authority comes from the reviewed repository revision and checkout. The guidance now fails closed when the authorized configuration is absent and keeps operator-managed, user-selected, and externally acquired configuration outside this contract.

Related Issue(s)

Fixes #2838

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 hve-builder and addressed all actionable findings
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)
• Copilot hook (.github/hooks/*/*.json)
• Eval spec added/updated for changed AI artifacts (evals/)

Note for AI Artifact Contributors:

• Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.
• Skills: Must include both bash and PowerShell scripts. See Skills.
• Model Versions: Contributions MUST target models listed in the model catalog (scripts/linting/model-catalog.json) whose provider appears in providerAllowlist and whose status is ga or preview. Run npm run lint:models to validate references.
• See Agents Not Accepted and Model Version Requirements.

Other:

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

Sample Prompts (for AI Artifact Contributions)

User Request:

Author or review a Bash script that sources repository-managed CI configuration.

Execution Flow:

1. Treat sourced configuration as executable code.
2. Establish authority from the reviewed repository revision and resulting checkout.
3. Use the expected checkout path and fail closed when the authorized file is absent.
4. Do not silently substitute configuration or apply the CI contract to other ownership classes.

Output Artifacts:

The instruction directly creates no artifact. It governs Bash content and reviews for matching .sh files.

Success Indicators:

Generated or reviewed guidance uses reviewed-checkout authority, identifies substitution and post-checkout modification as invalidating events, fails when authorized configuration is absent, and preserves the separate policy boundary for non-CI configuration.

For detailed contribution requirements, see:

• Common Standards: docs/contributing/ai-artifacts-common.md - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing
• Agents: docs/contributing/custom-agents.md - Agent configurations with tools and behavior patterns
• Prompts: docs/contributing/prompts.md - Workflow-specific guidance with template variables
• Instructions: docs/contributing/instructions.md - Technology-specific standards with glob patterns
• Skills: docs/contributing/skills.md - Task execution utilities with cross-platform scripts

Testing

• Focused Markdown lint passed for the changed instruction.
• Frontmatter, asset documentation, plugin membership, and whitespace validation passed during implementation.
• Static acceptance assertions passed for CI scope, authority, invalidation, fail-closed behavior, and the non-CI boundary.
• Post-rebase spell checking and diff whitespace validation passed.
• Post-rebase local aggregate and link validation were unavailable because the repository-wide external-link checker stalled without producing a result; the user deferred those checks to hosted CI.
• The lead developer and RAI champion reviewed and attested to the exact source and diff hashes.
• Manual runtime testing was not performed because no configuration fixture was sourced or executed.

Checklist

Required Checks

• Documentation is updated (N/A - no docs/ file changed)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (N/A - instruction-only change)

AI Artifact Contributions

• Used hve-builder review mode to review contribution
• Addressed all actionable findings from the hve-builder review
• Verified contribution follows common standards and type-specific requirements

Required Local Checks

The following local-safe validation commands must pass before merging:

• Local validation aggregate: npm run validate:local
• Documentation validation (N/A - no docs changed): npm run validate:docs
• Spell checking: npm run spell-check
• Link validation: npm run lint:md-links

Security Considerations

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

Additional Notes

The .ci/config.sh path is illustrative; this PR does not add or claim an existing runtime configuration file. The change defines authoring guidance, not a runtime verification mechanism. Local aggregate and link validation remain unchecked because external requests stalled; hosted CI must provide the final link-check result. Package-wide P08 acceptance and non-CI configuration policy remain outside this PR.

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.24%. Comparing base (bb0ac58) to head (8420c61).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2846      +/-   ##
==========================================
+ Coverage   83.14%   83.24%   +0.09%     
==========================================
  Files         183      172      -11     
  Lines       34039    34350     +311     
  Branches       27        0      -27     
==========================================
+ Hits        28302    28594     +292     
- Misses       5734     5756      +22     
+ Partials        3        0       -3     

Flag	Coverage Δ
docusaurus	?
pester	84.24% <ø> (+0.40%)	⬆️

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Eval Execution

✅ Status: Passed — no merge-blocking failures (2 advisory assertion failure(s) present)

• Artifacts evaluated: 1
• Specs run: 1
• Assertions passed: 7
• Assertions failed (blocking): 0
• Assertions failed (advisory): 2
• Failed specs (merge-blocking): 0

Artifact	Kind	Status	Specs	Passed	Failed (blocking)	Failed (advisory)
bash	instruction	⚠️ advisory-fail	1	7	0	2

Legend — ✅ clean · ⚠️ advisory failures only (non-blocking) · ⏭️ skipped · ❌ merge-blocking failure

Only Failed specs (merge-blocking) gates this PR. Advisory assertion failures are signal-quality checks captured during iteration; review them, but they do not block merge and may be acceptable.