Address PR #362 review (gwharris7): fix Copilot install + maturity docs, add faithful invocation exit-code tests

- a365-evaluate-instructions.md: the pipeline invokes the standalone GitHub
  Copilot CLI (binary `copilot`), not the `gh copilot` extension, so verify is
  now `copilot --version` and install is `npm install -g @github/copilot`
  (corrected consistently in the note, verify step, install, and troubleshooting).
- a365-evaluate-instructions.md: maturity levels corrected from 1-5 to the actual
  0-4 scale (Functional..Exemplary); triage bands remapped to the real
  MaturityCalculator thresholds.
- EvaluateCommandInvocationTests.cs: add faithful invocation-layer exit-code tests
  (invalid --eval-engine -> 3, missing --server-url -> 1, whitespace --output-dir
  -> 1, plus arg-propagation) via a parser that mirrors the Program.cs
  Agent365Exception.ExitCode mapping over a real pipeline with mocked sub-deps.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ashragrawal

docs/agent365-guided-setup/a365-evaluate-instructions.md

@@ -40,7 +40,7 @@ Wait for the answer. Store as `evalEngine`:
 - If **3 (Claude Code)**: `evalEngine = "claude-code"`
 - If **4 (None)**: `evalEngine = "none"`
 
-> **Note:** Auto and the named engines require the corresponding CLI to be installed on the workstation (`gh copilot` or `claude`). If neither is installed and `evalEngine` is `auto` or a named engine, the pipeline will stop after writing the checklist and print BYO-LLM instructions — that is expected, not an error.
+> **Note:** Auto and the named engines require the corresponding CLI to be installed on the workstation (`copilot` or `claude`). If neither is installed and `evalEngine` is `auto` or a named engine, the pipeline will stop after writing the checklist and print BYO-LLM instructions — that is expected, not an error.
 
 After all three questions are answered, create all todos for the path and mark Todo 1 in-progress:
 
@@ -106,14 +106,14 @@ The evaluation pipeline scores semantic checks (tool-name clarity, description q
 
 ### If `evalEngine = "github-copilot"` or `"auto"`
 
-Verify GitHub Copilot CLI is installed:
+Verify the GitHub Copilot CLI is installed:
 
 ```bash
-gh copilot --version
+copilot --version
 ```
 
 - If installed: continue.
-- If not installed: install with `gh extension install github/gh-copilot` (requires `gh` CLI). If `gh` itself is missing, see [GitHub CLI install](https://cli.github.com/).
+- If not installed: install with `npm install -g @github/copilot` (requires Node.js 18 or later). This is the standalone GitHub Copilot CLI (binary `copilot`) that the pipeline invokes — it is a different tool from the `gh copilot` GitHub CLI extension, which does not accept the flags the pipeline uses.
 
 ### If `evalEngine = "claude-code"` or `"auto"` (and Copilot was not found)
 
@@ -224,15 +224,15 @@ The CLI logs progress in numbered steps `[1/5]` through `[5/5]`:
 The report has:
 
 - **Overall score** (0–100). Higher is better.
-- **Maturity level** (1–5): Level 1 (Initial) → Level 5 (Optimized).
+- **Maturity level** (0–4): Level 0 (Functional) → Level 4 (Exemplary).
 - **Per-tool scores** with category breakdowns: schema quality, semantic clarity, parameter quality, return-shape quality.
 - **Action item list**, ordered by impact.
 
 ### Triage with the user
 
-1. **If overall score is below 60 or maturity is Level 1–2**, walk through the top 3 action items with the user. These usually cluster around: tool names that don't describe the action, descriptions that are stubs, parameter names that are abbreviations.
-2. **If overall score is 60–80 or maturity is Level 3**, the schema is shippable but has room. Pick 1–2 high-impact action items to address.
-3. **If overall score is above 80 or maturity is Level 4–5**, summarize the strengths and surface any low-hanging fixes.
+1. **If overall score is below 60 or maturity is Level 0–1 (Functional/Described)**, walk through the top 3 action items with the user. These usually cluster around: tool names that don't describe the action, descriptions that are stubs, parameter names that are abbreviations.
+2. **If overall score is 60–74 or maturity is Level 2 (Consistent)**, the schema is shippable but has room. Pick 1–2 high-impact action items to address.
+3. **If overall score is 75 or above or maturity is Level 3–4 (Optimized for AI/Exemplary)**, summarize the strengths and surface any low-hanging fixes.
 
 ### Re-running after fixes
 
@@ -267,7 +267,7 @@ If any step results in an error, stop and analyze the error message carefully.
 |---|---|---|
 | `Unauthorized` from `tools/list` | Wrong or expired bearer token | Re-acquire the token (Question 2). |
 | `Could not parse server URL` | URL doesn't include the protocol | Add `http://` or `https://` to the URL. |
-| `No coding agent detected` after `[2/5]` | Neither `gh copilot` nor `claude` is on PATH | Install one (Step 2) or pass `--eval-engine none`. |
+| `No coding agent detected` after `[2/5]` | Neither `copilot` nor `claude` is on PATH | Install one (Step 2) or pass `--eval-engine none`. |
 | `Failed to write report to <path>` | Output dir not writable | Choose a different `--output-dir` or fix permissions. |
 | Telemetry warning at debug level | Non-blocking — the marker call failed | Ignore. The evaluation runs regardless. |
 

src/Tests/Microsoft.Agents.A365.DevTools.Cli.Tests/Commands/EvaluateCommandInvocationTests.cs

@@ -2,11 +2,16 @@
 // Licensed under the MIT License.
 
 using System.CommandLine;
+using System.CommandLine.Builder;
+using System.CommandLine.Invocation;
+using System.CommandLine.Parsing;
 using FluentAssertions;
 using Microsoft.Agents.A365.DevTools.Cli.Commands;
+using Microsoft.Agents.A365.DevTools.Cli.Exceptions;
 using Microsoft.Agents.A365.DevTools.Cli.Services;
 using Microsoft.Agents.A365.DevTools.Cli.Services.Evaluate;
 using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
 using NSubstitute;
 using Xunit;
 
@@ -101,4 +106,96 @@ await pipeline.Received(1).RunAsync(
             Environment.SetEnvironmentVariable(AuthTokenEnvVar, original);
         }
     }
+
+    // The bare Command.InvokeAsync(string) shortcut used above wraps every thrown exception
+    // as exit code 1 via System.CommandLine's default handler, so it cannot observe an
+    // EvaluationException's ExitCode (3). The tests below build a parser that mirrors the
+    // exception-to-exit-code mapping in Program.cs (Agent365Exception.ExitCode) plus its
+    // parse-error short-circuit, and drive a real EvaluationPipelineService (sub-dependencies
+    // mocked) so ParseEvalEngine and the output-dir guard actually run. This pins the
+    // invocation-layer exit codes against a refactor of the SetHandler wiring that would
+    // otherwise break those branches with all tests still green.
+    private static Parser BuildFaithfulParser(Command evaluate) =>
+        new CommandLineBuilder(evaluate)
+            .UseExceptionHandler((exception, context) =>
+                context.ExitCode = exception is Agent365Exception agentEx ? agentEx.ExitCode : 1)
+            .AddMiddleware(async (context, next) =>
+            {
+                // Mirror Program.cs: a parse error (e.g. a missing required option) exits
+                // non-zero before the command handler runs.
+                if (context.ParseResult.Errors.Count > 0)
+                {
+                    context.ExitCode = 1;
+                    return;
+                }
+
+                await next(context);
+            }, MiddlewareOrder.ErrorReporting)
+            .Build();
+
+    // Real pipeline so ParseEvalEngine and the output-dir guard execute; the sub-dependencies
+    // are mocked because the failure paths under test throw or return before reaching them.
+    private static IEvaluationPipelineService RealPipeline() =>
+        new EvaluationPipelineService(
+            NullLogger<EvaluationPipelineService>.Instance,
+            Substitute.For<ISchemaDiscoveryService>(),
+            Substitute.For<IChecklistGenerator>(),
+            Substitute.For<IChecklistEvaluator>(),
+            Substitute.For<IEvaluationAnalyzer>(),
+            Substitute.For<IReportGenerator>(),
+            Substitute.For<IAgent365ToolingService>());
+
+    [Fact]
+    public async Task InvokeAsync_InvalidEvalEngine_ReturnsEvaluationExceptionExitCode3()
+    {
+        var evaluate = GetEvaluateSubcommand(Substitute.For<ILogger>(), RealPipeline());
+        var parser = BuildFaithfulParser(evaluate);
+
+        var exitCode = await parser.InvokeAsync(
+            new[] { "--server-url", "http://localhost/mcp", "--eval-engine", "bogus" });
+
+        exitCode.Should().Be(3, because: "an unknown --eval-engine raises an EvaluationException, whose ExitCode (3) the real exception handler must propagate to the process");
+    }
+
+    [Fact]
+    public async Task InvokeAsync_MissingServerUrl_ReturnsExitCode1()
+    {
+        var evaluate = GetEvaluateSubcommand(Substitute.For<ILogger>(), PipelineReturning(0));
+        var parser = BuildFaithfulParser(evaluate);
+
+        var exitCode = await parser.InvokeAsync(new[] { "--eval-engine", "none" });
+
+        exitCode.Should().Be(1, because: "--server-url is a required option; the missing-required-option parse error must exit non-zero without invoking the handler");
+    }
+
+    [Fact]
+    public async Task InvokeAsync_WhitespaceOutputDir_ReturnsExitCode1()
+    {
+        var evaluate = GetEvaluateSubcommand(Substitute.For<ILogger>(), RealPipeline());
+        var parser = BuildFaithfulParser(evaluate);
+
+        var exitCode = await parser.InvokeAsync(
+            new[] { "--server-url", "http://localhost/mcp", "--output-dir", "   ", "--eval-engine", "none" });
+
+        exitCode.Should().Be(1, because: "an empty or whitespace --output-dir must fail fast with exit code 1 through the real handler wiring, not a deep exception later in the run");
+    }
+
+    [Fact]
+    public async Task InvokeAsync_ValidArguments_ForwardsEachOptionToRunAsync()
+    {
+        var pipeline = PipelineReturning(0);
+        var evaluate = GetEvaluateSubcommand(Substitute.For<ILogger>(), pipeline);
+        var parser = BuildFaithfulParser(evaluate);
+
+        var exitCode = await parser.InvokeAsync(
+            new[] { "--server-url", "http://localhost:5000/mcp", "--output-dir", "out", "--eval-engine", "claude-code" });
+
+        exitCode.Should().Be(0, because: "RunAsync returned 0, which the handler must propagate as the process exit code");
+        await pipeline.Received(1).RunAsync(
+            "http://localhost:5000/mcp",
+            "out",
+            "claude-code",
+            Arg.Any<string?>(),
+            Arg.Any<CancellationToken>());
+    }
 }