1901 aligning coding standards skill discovery

[vdstrizhkova]

Pull Request

Description

Aligns the Code Review Standards perspective with platform-supported coding-standards skill discovery roots for issue #1901.

This PR updates the coding-standards standards subagent and docs to clarify that skill discovery starts from supported roots, then semantic matching selects relevant discovered candidates. It also documents same-name de-duplication, repository precedence over the built-in baseline, additive stacking for distinct skill names, and visible handling for contradictory distinct skills.

The change adds advisory Vally coverage for the requested merge-policy scenarios: no conflict, same-name collision, and contradictory distinct skills.

Related Issue(s)

Fixes #1901

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)
• 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: Only contributions targeting the latest Anthropic and OpenAI models will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected.
• 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:

Run the Code Review Standards perspective on a Python diff when both built-in and repository-authored coding-standards skills are available.

Execution Flow:

1. The Code Review orchestrator prepares the review context and invokes the standards perspective.
2. The standards subagent discovers coding-standards skill candidates from the built-in hve-core baseline and supported repository or configured roots.
3. Same-named skills are de-duplicated before semantic selection, with repository-authored candidates taking precedence over the built-in baseline.
4. Distinct-named matching skills stack additively up to the configured limit.
5. Contradictory distinct skills surface findings from each skill instead of silently merging or suppressing either policy.

Output Artifacts:

• Standards findings from the Code Review Standards perspective.
• Updated documentation for language skill discovery and merge behavior.
• Updated advisory Vally stimuli and generated eval spec for the merge-policy scenarios.

Success Indicators:

• Same-named built-in and repository skills do not both load.
• Repository-authored same-name skills take precedence over the built-in baseline.
• Distinct-named skills apply together when both match the changed files.
• Contradictory distinct skills are both surfaced for reviewer judgment.
• Focused merge-policy Vally scenarios pass.

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

Automated validation performed:

• pwsh scripts/evals/Build-AgentBehaviorSpec.ps1 -Force - passed

• npm run eval:lint:schema - passed

  • 10 specs validated successfully
  • Agent behavior coverage: 48 covered, 0 missing

• Focused advisory Vally eval - passed

  Command: npx vally eval --eval-spec evals/agent-behavior/eval.yaml --tag scenario=merge-no-conflict,merge-name-collision,merge-content-contradiction --runs 1 --output-dir /tmp/vally-merge-results

  Result: agent-behavior: passed (score: 100.0%, threshold: 70.0%)

• npm run lint:md -- docs/agents/code-review/language-skills.md docs/agents/code-review/README.md .github/agents/coding-standards/subagents/code-review-standards.agent.md - passed

• npm run lint:frontmatter - passed

  • 801 files validated
  • 0 errors, 0 warnings

• npm run lint:md-links - passed

• npm run spell-check - passed

  • 657 files checked
  • 0 issues

• git diff --check -- .github/agents/coding-standards/subagents/code-review-standards.agent.md docs/agents/code-review/README.md docs/agents/code-review/language-skills.md evals/agent-behavior/stimuli/code-review-standards.yml evals/agent-behavior/eval.yaml - passed

• VS Code diagnostics on touched files - passed

  • No errors found

Manual testing was not performed.

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

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 (N/A - no skill files changed)
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps (N/A - no PowerShell files changed)
• Eval spec schema and coverage (if AI artifacts changed): npm run eval:lint:schema
• 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 (N/A - no dependency changes)
• Security-related scripts follow the principle of least privilege (N/A - no security scripts changed)

GHCP Artifact Maturity

Warning

This PR includes experimental GHCP artifacts that may have breaking changes.

• .github/agents/coding-standards/subagents/code-review-standards.agent.md

File	Type	Maturity	Notes
.github/agents/coding-standards/subagents/code-review-standards.agent.md	Agent	experimental	Standards perspective subagent

GHCP Maturity Acknowledgment

• I acknowledge this PR includes non-stable GHCP artifacts
• Non-stable artifacts are intentional for this change

Additional Notes

This PR is intentionally scoped to coding-standards discovery and merge behavior only. It does not broaden security or accessibility skill discovery.

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.69%. Comparing base (9202542) to head (12bf7d3).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2358      +/-   ##
==========================================
- Coverage   83.00%   81.69%   -1.31%     
==========================================
  Files         185      163      -22     
  Lines       34924    22753   -12171     
  Branches      228       27     -201     
==========================================
- Hits        28989    18589   -10400     
+ Misses       5861     4161    -1700     
+ Partials       74        3      -71     

Flag	Coverage Δ
docusaurus	90.60% <ø> (ø)
pester	83.41% <ø> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 51 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.

[Bill Berry (WilliamBerryiii)]

It looks like either the eval matrix job is broken, or the discovery system has a bug as the evals weren't run over the new tests. Might want to do a root cause analysis on that and file a bug.

[vdstrizhkova]

Bill Berry (@WilliamBerryiii) thanks for the review!
The issue with running the tests is that by default sub-agents are not run.
There are two ways to fix it: move the tests to the parent code-standards agent (with the loss of granularity) or enable the run of sub-agents. I opted right now for the first option as the second will bring a lot of changes to the PR. Please let me know if you want me to open a ticket and look into the sub-agents tests run separately or in this PR