fix(azure.ai.agents): align doctor types to design spec

Cross-checked the committed Phase 4.1 doctor types (`internal/cmd/doctor/
types.go`) against the JSON envelope contract in the design spec
(`cli/azd/docs/design/azd-ai-agent-nextsteps.md`, lines 357-383). Found
nine drift deltas. Per the user's "design spec is a guide, not a
contract — keep what's better" direction, this commit adopts the design's
unintentional-drift fixes and documents the deliberate improvements that
diverge from the spec.

Adopted from the design spec
- `CurrentSchemaVersion`: "1" → "1.0" (standard semver-ish form).
- New field `Result.Links []string` (`json:"links,omitempty"`) for
  TSG / docs URLs surfaced by Phase 5 remote checks.
- New field `Result.DurationMs int64` (`json:"durationMs,omitempty"`)
  populated by the runner via `time.Since(start).Milliseconds()`.
  Observability for slow checks.
- `Report.Summary` JSON tag → `json:"-"`. Still computed in-memory and
  consumed by `Report.ExitCode()`; not part of the wire format.
  Consumers can compute it from `checks[]` if needed.
- Namespaced check IDs (e.g., `local.azure-yaml`, `remote.rbac`) called
  out in doc comments. Phase 4.2 onward emits IDs in this form.

Kept as deliberate improvements over the design spec
- JSON tags `name`/`message`/`suggestion` retained (design uses
  `title`/`detail`/`fix`). `name` is shorter and universal; `message`
  is primary text vs `detail`'s "supplementary" connotation;
  `suggestion` is broader than `fix` (covers warnings, not just
  blocking failures).
- `Result.Details map[string]any` (`json:"details,omitempty"`) kept
  as the design-spec extension for Phase 5 RBAC payloads (role lists,
  scope ARNs, etc.). Doc comment now explicitly identifies this as a
  documented extension.

Runner
- `runner.go` now wraps every `check.Fn(...)` call with `start :=
  time.Now()` / `result.DurationMs = time.Since(start).
  Milliseconds()`. Single integration point, applies uniformly to all
  checks present and future.

Tests
- `TestRunner_Run_DurationMsIsPopulated` — 5ms sleep inside a check
  function, asserts `DurationMs >= 1`. All 16 existing tests still
  pass.

Cspell
- Added `nextsteps` override for `internal/cmd/doctor/types.go`.
  Doc comments now reference the design doc filename
  (`azd-ai-agent-nextsteps.md`), which trips the existing `nextstep`
  (singular) entry.

No new review pass on this commit — same trivial align-to-design shape
as 4.1.1 (precedent: doc/contract cleanups land pre-validated).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Antriksh Jain

cli/azd/.vscode/cspell.yaml

@@ -409,6 +409,9 @@ overrides:
   - filename: extensions/azure.ai.agents/internal/cmd/init_locations.go
     words:
       - swedencentral
+  - filename: "**/extensions/azure.ai.agents/internal/cmd/doctor/types.go"
+    words:
+      - nextsteps
   - filename: docs/code-coverage-guide.md
     words:
       - covdata

cli/azd/extensions/azure.ai.agents/internal/cmd/doctor/runner.go

@@ -3,7 +3,10 @@
 
 package doctor
 
-import "context"
+import (
+	"context"
+	"time"
+)
 
 // CheckFunc is the signature every check satisfies. Checks are invoked
 // sequentially by the Runner; each receives the immutable Options and the
@@ -90,7 +93,9 @@ func (r *Runner) Run(ctx context.Context, opts Options) Report {
 			continue
 		}
 
+		start := time.Now()
 		result := check.Fn(ctx, opts, report.Checks)
+		result.DurationMs = time.Since(start).Milliseconds()
 		// Pin the ID + Name at the runner — the design's table is the
 		// source of truth, and individual check functions should not be
 		// able to drift from it.

cli/azd/extensions/azure.ai.agents/internal/cmd/doctor/runner_test.go

@@ -6,6 +6,7 @@ package doctor
 import (
 	"context"
 	"testing"
+	"time"
 
 	"github.com/stretchr/testify/require"
 )
@@ -322,3 +323,19 @@ func TestRunner_Run_UnredactedFlipsRedacted(t *testing.T) {
 
 	require.False(t, report.Redacted, "Unredacted true should flip Redacted to false")
 }
+
+func TestRunner_Run_DurationMsIsPopulated(t *testing.T) {
+	t.Parallel()
+
+	runner := &Runner{Checks: []Check{{ID: "1", Name: "x", Fn: func(_ context.Context, _ Options, _ []Result) Result {
+		// Sleep long enough that even a millisecond-resolution clock observes a tick.
+		time.Sleep(5 * time.Millisecond)
+		return Result{Status: StatusPass, Message: "ok"}
+	}}}}
+
+	report := runner.Run(t.Context(), Options{})
+
+	require.Len(t, report.Checks, 1)
+	require.GreaterOrEqual(t, report.Checks[0].DurationMs, int64(1),
+		"runner must time each check and stamp DurationMs (got %d)", report.Checks[0].DurationMs)
+}

cli/azd/extensions/azure.ai.agents/internal/cmd/doctor/types.go

@@ -19,13 +19,12 @@
 // can be unit-tested without a process-level shim.
 package doctor
 
-// CurrentSchemaVersion is the version stamped onto the JSON envelope. Bump
-// when the JSON shape changes in a non-additive way; additive changes
-// (new optional fields, new status values that consumers can ignore) do
-// not require a bump. Consumers should treat unknown statuses as "pass"
-// for the purposes of summary aggregation only when this version equals
-// the one they were built against.
-const CurrentSchemaVersion = "1"
+// CurrentSchemaVersion is the version stamped onto the JSON envelope. The
+// value matches the design spec (`docs/design/azd-ai-agent-nextsteps.md`,
+// "Exit codes & JSON output" section). Bump on non-additive shape changes;
+// additive changes (new optional fields, new status values) do not require
+// a bump.
+const CurrentSchemaVersion = "1.0"
 
 // Status is the outcome of a single check. The set is closed; runners and
 // formatters branch exhaustively on these four values.
@@ -49,21 +48,30 @@ const (
 
 // Result captures the outcome of one check.
 //
-// ID is a stable identifier (the design pins these to "1".."12"). Name is
-// a short human-readable title for the text formatter; Message is the
-// one-line summary that always renders. Details and Suggestion are
-// optional — Details is a structured map for machine consumers (the JSON
-// formatter emits it as an object; the text formatter renders each
-// key-value pair on an indented line), Suggestion is a single actionable
-// command or instruction (the text formatter renders it on its own line
-// prefixed with "→ ").
+// ID is a stable namespaced identifier (`local.azure-yaml`,
+// `remote.rbac`, etc.). Name is a short human-readable title; Message is
+// the one-line summary that always renders. Suggestion is a single
+// actionable command or instruction (the text formatter renders it after
+// the message, indented). Links is an optional slice of URLs (TSG pages,
+// learn.microsoft.com docs) that the formatter renders below the
+// suggestion. DurationMs is populated by the Runner per check.
+//
+// JSON tags are extension-owned: the wire shape includes `links` and
+// `durationMs` (matching the design spec at
+// `docs/design/azd-ai-agent-nextsteps.md`) plus a `details` extension
+// field (omitted from the design's example but required for Phase 5
+// remote checks that surface structured payload — role lists, scope
+// ARNs). `details` is `omitempty`, so consumers built against the
+// design's schema ignore the extra field and remain compatible.
 type Result struct {
 	ID         string         `json:"id"`
 	Name       string         `json:"name"`
 	Status     Status         `json:"status"`
 	Message    string         `json:"message,omitempty"`
-	Details    map[string]any `json:"details,omitempty"`
 	Suggestion string         `json:"suggestion,omitempty"`
+	Links      []string       `json:"links,omitempty"`
+	DurationMs int64          `json:"durationMs,omitempty"`
+	Details    map[string]any `json:"details,omitempty"`
 }
 
 // Summary is the aggregate count of results by status. Computed by the
@@ -81,12 +89,17 @@ type Summary struct {
 // checks are wired. Redacted is the inverse of the --unredacted flag and
 // indicates whether the formatter scrubbed identifiers in user-facing
 // strings.
+//
+// Summary is computed by the Runner for ExitCode and the text formatter,
+// but is excluded from the JSON envelope (consumers iterate Checks if they
+// need totals). Excluding it keeps the wire shape aligned with the design
+// spec.
 type Report struct {
 	SchemaVersion string   `json:"schemaVersion"`
 	Remote        bool     `json:"remote"`
 	Redacted      bool     `json:"redacted"`
 	Checks        []Result `json:"checks"`
-	Summary       Summary  `json:"summary"`
+	Summary       Summary  `json:"-"`
 }
 
 // Options are the runtime flags that influence the runner. LocalOnly