fix(extension): resolve handoff dependencies using display names

[agreaves-ms]

The Resolve-HandoffDependencies function in the extension packaging pipeline silently skipped handoff targets declared by display name. Agent frontmatter uses display names (e.g., "Task Planner") in handoff declarations, but the resolver matched only by file stem (e.g., task-planner), causing transitive dependencies to be dropped from packaged extensions. This fix builds an upfront index mapping both display names and file stems to agent files, replacing per-iteration filesystem lookups with O(1) hashtable resolution.

Description

The core issue: handoff declarations in agent frontmatter reference targets by display name, but the BFS traversal only searched for files by stem pattern. Any display-name handoff target was logged as "not found" and omitted from the transitive closure, leading to incomplete extension packages.

Bug Fix

Rewrote the lookup mechanism in Resolve-HandoffDependencies to pre-scan all .agent.md files and build a name index keyed by both file stem and YAML frontmatter name field. During BFS traversal, handoff targets now resolve via direct hashtable lookup regardless of whether they are specified as stems or display names.

• Added index construction that scans *.agent.md files once, extracts file stems and parses YAML frontmatter for display names with first-writer-wins collision handling
• Replaced per-iteration Get-ChildItem -Filter calls with $agentIndex[$current] lookups, reducing filesystem calls from O(n) to O(1) per BFS node
• Added stem normalization after lookup: when a display name resolves to a file, the file stem is added to the visited set, ensuring downstream collection filtering sees consistent keys
• Updated warning messages to reference $agentFile.Name instead of interpolating $current.agent.md, which produced incorrect output for display-name entries
• Clarified comment-based help to document that inputs and outputs are file stems and that the function resolves both naming formats

Test Coverage

Added a new Describe 'Resolve-HandoffDependencies - display name resolution' block with two test cases exercising the display-name path.

• Simple display-name handoff: a parent agent declares a handoff to "Child Agent" (display name), asserting both parent-agent and child-agent stems appear in the result set
• Circular display-name chain: task-planner hands off to "Task Implementor", which hands back to "Task Planner", validating that the visited-set terminates correctly with stem normalization and both stems are returned

Related Issue(s)

None

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)

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)

Testing

• Automated validation: PowerShell analysis (npm run lint:ps), markdown linting (npm run lint:md), frontmatter validation (npm run lint:frontmatter), skill structure validation (npm run validate:skills), link validation (npm run lint:md-links) results documented below.
• Diff-based assessment: Verified index construction logic, BFS lookup replacement, stem normalization, and warning message fixes against source files.
• Security analysis: No sensitive data exposure, no dependency changes, no privilege escalation. Changes are internal to build tooling with no user-facing input vectors.
• Manual testing: Not performed.

Checklist

Required Checks

• Documentation is updated (if applicable) (N/A — no documentation changes required for this internal tooling fix)
• 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 (N/A — no AI artifact changes)
• Addressed all feedback from prompt-builder review (N/A — no AI artifact changes)
• Verified contribution follows common standards and type-specific requirements (N/A — no AI artifact changes)

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
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps
• Plugin freshness: npm run plugin:generate

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 script changes)

Additional Notes

• The first-writer-wins collision strategy for the agent index is a defensive choice: if a display name coincidentally matches another agent's file stem, the first entry takes precedence. No test covers this edge case but the guard prevents ambiguity.
• Existing stem-based tests in the prior Describe 'Resolve-HandoffDependencies' block remain unaffected.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@acd6539). Learn more about missing BASE report.
⚠️ Report is 7 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #727   +/-   ##
=======================================
  Coverage        ?   84.91%           
=======================================
  Files           ?       24           
  Lines           ?     4892           
  Branches        ?        0           
=======================================
  Hits            ?     4154           
  Misses          ?      738           
  Partials        ?        0           

Flag	Coverage Δ
pester	84.91% <100.00%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
scripts/extension/Prepare-Extension.ps1	94.45% <100.00%> (ø)

🚀 New features to boost your workflow:

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