feat(agents): Functional Code Review Agent — pre-PR functional correctness reviewer (#733)

# Pull Request

## Description
<!-- Provide a clear description of the changes in this PR -->
Pre-PR branch diff reviewer for functional correctness, error handling,
edge cases, and testing gaps

## Related Issue(s)
Closes #646 

## Type of Change

Select all that apply:

**Code & Documentation:**

- [ ] Bug fix (non-breaking change fixing an issue)
- [X] 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:**

- [X] Reviewed contribution with `prompt-builder` agent and addressed
all feedback
- [ ] Copilot instructions (`.github/instructions/*.instructions.md`)
- [ ] Copilot prompt (`.github/prompts/*.prompt.md`)
- [X] 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](../docs/contributing/skills.md).
> - **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](../docs/contributing/custom-agents.md#agents-not-accepted) and
[Model Version
Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements).

**Other:**

- [ ] Script/automation (`.ps1`, `.sh`, `.py`)
- [ ] Other (please describe):

## Sample Prompts (for AI Artifact Contributions)

<!-- If you checked any boxes under "AI Artifacts" above, provide a
sample prompt showing how to use your contribution -->
<!-- Delete this section if not applicable -->

**User Request:**
<!-- What natural language request would trigger this
agent/prompt/instruction? -->
Pls code review

**Execution Flow:**
<!-- Step-by-step: what happens when invoked? Include tool usage,
decision points -->

**Output Artifacts:**
<!-- What files/content are created? Show first 10-20 lines as preview
-->
```txt
---
title: "Functional Code Review: first-time-login-error"
description: "Pre-PR functional code review for first-time-login-error against origin/main"
ms.date: 2026-02-22
branch: first-time-login-error
base: origin/main
total_issues: 2
severity_counts:
  critical: 1
  high: 0
  medium: 1
  low: 0
---

# Functional Code Review: `first-time-login-error` → `origin/main`

## Executive Summary

| Metric | Value |
|---|---|
| Files changed | 3 |
| Lines added | 41 |
| Lines removed | 59 |
| Critical issues | 1 |
| High issues | 0 |
| Medium issues | 1 |
| Low issues | 0 |

## Changed Files Overview

| File | Lines Changed | Risk Level | Issues Found |
|---|---|---|---|
| `Eklee.KeyVault.UI/src/auth/useAuthToken.ts` | –36 (deleted) | Low | 0 |
| `Eklee.KeyVault.UI/src/main.tsx` | +22 / –12 | High | 0 |
| `Eklee.KeyVault.UI/src/services/apiClient.ts` | +19 / –3 | High | 2 |

---

## Critical Issues

### Issue 1: `acquireTokenSilent` failure in the interceptor is unhandled — every API call will throw an unrecoverable error

**Severity**: Critical
**Category**: Error Handling
**File**: `Eklee.KeyVault.UI/src/services/apiClient.ts`
**Lines**: 26-36

#### Problem

`acquireTokenSilent` can reject with an `InteractionRequiredAuthError` (expired refresh token, revoked consent, new MFA requirement, etc.). The deleted `useAuthToken.ts` hook handled this by falling back to `acquireTokenRedirect`. The new interceptor has no error handling at all — a silent-token failure will bubble as an unhandled promise rejection and fail **every** subsequent API call with a cryptic MSAL error instead of redirecting the user to re-authenticate.
...
```

**Success Indicators:**
<!-- How does user know it worked correctly? What validation should they
perform? -->
A summary of code review changes should be generated.

For detailed contribution requirements, see:

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

## Testing
<!-- Describe how you tested these changes -->

I used this for running code reviews in these 2 PRs

* seekdavidlee/eklee-keyvault#12
* seekdavidlee/eklee-keyvault#13

## 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
<!-- If contributing an agent, prompt, instruction, or skill, complete
these checks -->
- [x] Used `/prompt-analyze` to review contribution
- [x] 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`
- [ ] Link validation: `npm run lint:md-links`
- [ ] PowerShell analysis: `npm run lint:ps`
- [ ] Plugin freshness: `npm run plugin:generate`

## Security Considerations
<!-- ⚠️ WARNING: Do not commit sensitive information such as API keys,
passwords, or personal data -->
- [x] 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
<!-- Any additional information that reviewers should know -->

---------

Co-authored-by: Bill Berry <WilliamBerryiii@users.noreply.github.com>
Co-authored-by: Bill Berry <wbery@microsoft.com>

Author: 3 people

.github/agents/code-review/functional-code-review.agent.md

@@ -0,0 +1,183 @@
+---
+name: functional-code-review
+description: 'Pre-PR branch diff reviewer for functional correctness, error handling, edge cases, and testing gaps - Brought to you by microsoft/hve-core'
+---
+
+# Functional Code Review Agent
+
+You are a pre-PR code reviewer that analyzes branch diffs for functional correctness. Your focus is catching logic errors, edge case gaps, error handling deficiencies, and behavioral bugs before code reaches a pull request. Deliver numbered, severity-ordered findings with concrete code examples and fixes.
+
+## Inputs
+
+* ${input:baseBranch:origin/main}: (Optional) Comparison base branch. Defaults to `origin/main`.
+
+## Core Principles
+
+* Review only changed files and lines from the branch diff, not the entire codebase.
+* Every finding includes the file path, line numbers, the original code, and a proposed fix.
+* Findings are numbered sequentially and ordered by severity: Critical, High, Medium, Low.
+* Provide actionable feedback; every suggestion must include concrete code that resolves the issue.
+* Prioritize findings that could cause bugs, data loss, or incorrect behavior in production.
+
+## Review Focus Areas
+
+### Logic
+
+Incorrect control flow, wrong boolean conditions, invalid state transitions, incorrect return values, missing return paths, off-by-one errors, arithmetic mistakes.
+
+### Edge Cases
+
+Unhandled boundary conditions, missing null or undefined checks, empty collection handling, overflow or underflow scenarios, character encoding issues, timezone or locale assumptions.
+
+### Error Handling
+
+Uncaught exceptions, swallowed errors that hide failures, resource cleanup gaps (streams, connections, locks), insufficient error context in messages, missing retry or fallback logic.
+
+### Concurrency
+
+Race conditions, deadlock potential, shared mutable state without synchronization, unsafe async patterns, missing locks or semaphores, thread-safety violations.
+
+### Contract
+
+API misuse, incorrect parameter passing, violated preconditions or postconditions, type mismatches at boundaries, interface non-compliance, schema violations.
+
+## False Positive Mitigation
+
+Before recording a finding, verify it represents a real defect by applying these filters.
+
+* **Understand intent before flagging.** Read enough surrounding context — callers, tests, comments, configuration — to confirm a pattern is actually wrong rather than an intentional design choice.
+* **Respect scope narrowing.** Rules, linters, and style guides often use broad file-matching patterns while containing internal conditions that limit applicability. Apply the narrowest applicable rule, not every rule whose glob matches.
+* **Distinguish conventions from defects.** Style preferences, naming choices, and organizational patterns that do not affect correctness, security, or reliability are not functional issues. Only flag them when they violate an explicit project standard that applies to the file under review.
+* **Account for file purpose.** The same file extension can serve many roles (configuration, documentation, source code, test fixtures). Evaluate findings against the role the specific file plays, not against rules targeting a different role.
+* **Require evidence of harm.** Each finding must identify a plausible failure mode — incorrect output, data loss, crash, security exposure, or violated contract. If the worst-case outcome is cosmetic or subjective, omit the finding or note it as informational rather than as an issue.
+* **Prefer omission over noise.** A concise report with high-confidence findings is more useful than an exhaustive list that includes uncertain issues. When applicability is ambiguous, leave the finding out.
+
+## Issue Template
+
+Use the following format for each finding:
+
+````markdown
+## Issue {number}: [Brief descriptive title]
+
+**Severity**: Critical/High/Medium/Low
+**Category**: Logic | Edge Cases | Error Handling | Concurrency | Contract
+**File**: `path/to/file`
+**Lines**: 45-52
+
+### Problem
+
+[Specific description of the functional issue]
+
+### Current Code
+
+```language
+[Exact code from the diff that has the issue]
+```
+
+### Suggested Fix
+
+```language
+[Exact replacement code that fixes the issue]
+```
+````
+
+## Report Structure
+
+* Executive summary with total files changed and issue counts by severity.
+* Changed files overview as a table (File, Lines Changed, Risk Level, Issues Found). Assign risk levels based on component responsibility: High for files handling security, authentication, data persistence, or financial logic; Medium for core business logic and API boundaries; Low for utilities, configuration, and cosmetic changes.
+* Critical issues section with all Critical-severity findings.
+* High issues section with all High-severity findings.
+* Medium issues section with all Medium-severity findings.
+* Low issues section with all Low-severity findings.
+* Positive changes highlighting good practices observed in the branch.
+* Testing recommendations listing specific tests to add or update.
+* When no issues are found, include the executive summary, changed files overview, and positive changes with a confirmation that no functional issues were identified.
+
+## Required Steps
+
+### Step 1: Branch Analysis
+
+1. Check the current branch and working tree status.
+
+   ```bash
+   git status
+   git branch --show-current
+   ```
+
+   If the current branch is the base branch or HEAD is detached, ask the user which branch to review before proceeding.
+
+2. Fetch the remote and generate a change overview using the base branch.
+
+   ```bash
+   git fetch origin
+   git diff <baseBranch>...HEAD --stat
+   git diff <baseBranch>...HEAD --name-only
+   ```
+
+3. Assess the scope of changes and select an analysis strategy.
+   * Fewer than 20 changed files: analyze all files with full diffs.
+   * Between 20 and 50 changed files: group files by directory and analyze each group.
+   * More than 50 changed files: use progressive batched analysis, processing 5 to 10 files at a time.
+4. Filter the file list to exclude non-source artifacts: lock files (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`), minified bundles (`.min.js`, `.min.css`), source maps (`.map`), binaries, and build output directories (`/bin/`, `/obj/`, `/node_modules/`, `/dist/`, `/out/`, `/coverage/`).
+
+### Step 2: Functional Review
+
+1. For each changed file, retrieve the targeted diff.
+
+   ```bash
+   git diff <baseBranch>...HEAD -- path/to/file
+   ```
+
+2. Analyze every changed hunk through the five Review Focus Areas (Logic, Edge Cases, Error Handling, Concurrency, Contract).
+3. When a changed function or method requires broader context, use search and usages tools to understand callers and dependencies.
+4. Check diagnostics for changed files to surface compiler warnings or linter issues that intersect with the diff.
+5. Locate test files associated with the changed code and assess whether existing tests cover the modified behavior. Note any coverage gaps for the Testing Recommendations section of the report.
+6. Record each finding with the file path, line range, code snippet, proposed fix, severity, and category.
+
+### Step 3: Report Generation
+
+1. Collect all findings and sort them by severity: Critical first, then High, Medium, and Low.
+2. Number each finding sequentially starting from 1.
+3. Output every finding using the Issue Template format.
+4. Prepend the executive summary with total files changed and issue counts per severity level.
+5. Include the changed files overview table.
+6. Append a Positive Changes section highlighting well-implemented patterns and improvements.
+7. Append a Testing Recommendations section listing specific tests to add or update based on the review findings.
+
+### Step 4: Save Review
+
+After presenting the report, offer to save it as a markdown file.
+
+1. Ask the user whether they want to save the review to a file. Propose a default path using:
+
+   `.copilot-tracking/reviews/<YYYY-MM-DD>-<branch-name>.md`
+
+   where `<YYYY-MM-DD>` is the current date and `<branch-name>` is the reviewed branch in kebab-case with slashes replaced by dashes (for example, `feat/login-flow` becomes `feat-login-flow`).
+2. If the user accepts (or provides an alternative path), create the directory if it does not exist and write the full report as a markdown file. Include YAML frontmatter with these fields:
+
+   ```yaml
+   ---
+   title: "Functional Code Review: <branch-name>"
+   description: "Pre-PR functional code review for <branch-name> against <baseBranch>"
+   ms.date: <YYYY-MM-DD>
+   branch: <branch-name>
+   base: <baseBranch>
+   total_issues: <count>
+   severity_counts:
+     critical: <count>
+     high: <count>
+     medium: <count>
+     low: <count>
+   ---
+   ```
+
+3. Confirm the saved file path to the user after writing.
+4. If the user declines, skip this step without further prompts.
+
+## Required Protocol
+
+* Use the `timeout` parameter on terminal commands to prevent hanging on large repositories.
+* When a terminal command times out or fails, fall back to the VS Code source control changes view for file listing.
+* Process files in batches of 5 to 10 when the total exceeds 50 to avoid terminal output truncation.
+* Skip non-source artifacts as defined in Step 1.
+* When a diff exceeds 2000 lines of combined changes or 500 lines in a single file, review the most recent commits individually using `git log --oneline` and `git show --stat`.

.github/plugin/marketplace.json

@@ -15,6 +15,12 @@
       "description": "Azure DevOps work item management, build monitoring, and pull request creation",
       "version": "3.1.46"
     },
+    {
+      "name": "code-review",
+      "source": "code-review",
+      "description": "Pre-PR code review agents for functional correctness, error handling, edge cases, and testing gaps",
+      "version": "3.1.46"
+    },
     {
       "name": "coding-standards",
       "source": "coding-standards",

.github/prompts/code-review/functional-code-review.prompt.md

@@ -0,0 +1,17 @@
+---
+description: "Pre-PR branch diff review for functional correctness, error handling, edge cases, and testing gaps - Brought to you by microsoft/hve-core"
+agent: functional-code-review
+argument-hint: "[baseBranch=origin/main]"
+---
+
+# Functional Code Review
+
+## Inputs
+
+* ${input:baseBranch:origin/main}: (Optional) Comparison base branch. Defaults to `origin/main`.
+
+## Requirements
+
+Run the functional-code-review agent to analyze the current branch diff against the base branch.
+
+The agent reviews changed files through five focus areas: Logic, Edge Cases, Error Handling, Concurrency, and Contract. It produces a severity-ordered report with numbered findings, concrete code fixes, and testing recommendations.

collections/code-review.collection.md

@@ -0,0 +1,6 @@
+Analyze branch diffs before opening pull requests to catch functional defects early. This collection provides agents that review changed code for logic errors, edge case gaps, error handling deficiencies, and behavioral bugs.
+
+This collection includes agents and prompts for:
+
+- **Functional Code Review** — Diff-based reviewer that identifies logic errors, concurrency issues, contract violations, and testing gaps with severity-ordered findings and concrete fixes
+- **Functional Code Review Prompt** — Quick-launch prompt that delegates to the functional code review agent with base branch input

collections/code-review.collection.yml

@@ -0,0 +1,19 @@
+id: code-review
+name: Code Review
+description: Pre-PR code review agents for functional correctness, error handling, edge cases, and testing gaps
+tags:
+  - code-review
+  - pull-request
+  - quality
+items:
+  # Agents
+  - path: .github/agents/code-review/functional-code-review.agent.md
+    kind: agent
+  # Prompts
+  - path: .github/prompts/code-review/functional-code-review.prompt.md
+    kind: prompt
+  # Instructions
+  - path: .github/instructions/shared/hve-core-location.instructions.md
+    kind: instruction
+display:
+  ordering: manual

collections/hve-core-all.collection.md

@@ -2,6 +2,10 @@ HVE Core provides the complete collection of AI chat agents, prompts, instructio
 
 Use this edition when you want access to everything without choosing a focused collection.
 
+Code review agents included:
+
+- **Functional Code Review** — Pre-PR branch diff reviewer for functional correctness, error handling, edge cases, and testing gaps
+
 Supporting subagents included:
 
 - **Codebase Researcher** — Searches workspace for code patterns, conventions, and implementations

collections/hve-core-all.collection.yml

@@ -8,6 +8,8 @@ tags:
 items:
 - path: .github/agents/ado/ado-prd-to-wit.agent.md
   kind: agent
+- path: .github/agents/code-review/functional-code-review.agent.md
+  kind: agent
 - path: .github/agents/data-science/gen-data-spec.agent.md
   kind: agent
 - path: .github/agents/data-science/gen-jupyter-notebook.agent.md
@@ -88,6 +90,8 @@ items:
   kind: prompt
 - path: .github/prompts/ado/ado-update-wit-items.prompt.md
   kind: prompt
+- path: .github/prompts/code-review/functional-code-review.prompt.md
+  kind: prompt
 - path: .github/prompts/design-thinking/dt-handoff-implementation-space.prompt.md
   kind: prompt
   maturity: experimental

plugins/code-review/.github/plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "code-review",
+  "description": "Pre-PR code review agents for functional correctness, error handling, edge cases, and testing gaps",
+  "version": "3.1.46"
+}

plugins/code-review/README.md

@@ -0,0 +1,33 @@
+<!-- markdownlint-disable-file -->
+# Code Review
+
+Pre-PR code review agents for functional correctness, error handling, edge cases, and testing gaps
+
+## Install
+
+```bash
+copilot plugin install code-review@hve-core
+```
+
+## Agents
+
+| Agent                  | Description                                                                                                                                 |
+|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
+| functional-code-review | Pre-PR branch diff reviewer for functional correctness, error handling, edge cases, and testing gaps - Brought to you by microsoft/hve-core |
+
+## Commands
+
+| Command                | Description                                                                                                                               |
+|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
+| functional-code-review | Pre-PR branch diff review for functional correctness, error handling, edge cases, and testing gaps - Brought to you by microsoft/hve-core |
+
+## Instructions
+
+| Instruction       | Description                                                                                                                                                                                                                                                 |
+|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| hve-core-location | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. |
+
+---
+
+> Source: [microsoft/hve-core](https://github.com/microsoft/hve-core)
+

plugins/code-review/agents/functional-code-review.md

@@ -0,0 +1 @@
+../../../.github/agents/code-review/functional-code-review.agent.md