docs(agents): add doctor storage permissions spec

[Yimin-Jin]

Summary

• Propose a project-to-Storage permission check in the existing azd ai agent doctor command, without new commands or parameters.
• Define when the project-identity RBAC check applies, skip account-key authentication, and provide remediation that identifies an administrator authorized to assign roles on the target Storage account.
• Preserve the existing diagnostic report and record the open question: which Storage and identity are used by azd ai agent optimize?

Related Issue

Design for #8665, formally linked in Development. This PR adds the spec only; it does not implement the diagnostic. GitHub will close #8665 when this PR is merged; implementation remains follow-up work.

Validation

• Documentation spelling check: 1 file checked, 0 issues.
• git diff --check: passed.
• Editor diagnostics: no errors.
• Documentation-only change; no runtime tests or Azure operations were performed.

[azure-pipelines]

Azure Pipelines:
22 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[azure-pipelines]

Azure Pipelines:
22 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

🟡 Changes recommended

The spec omits account-key authentication handling and gives imprecise role-assignment remediation.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Defines a proposed Storage RBAC diagnostic for azd ai agent doctor.

Changes:

• Specifies applicability, outcomes, and read-only behavior.
• Documents the existing report format and proposed failure guidance.

File summaries

File	Description
docs/specs/agent-doctor-storage-rbac/spec.md	Defines the proposed storage-permission check.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

📋 Prioritization Note

Thanks for the contribution! The linked issue isn't in the current milestone yet.
Thank you for logging this issue; our team is reviewing it. If you need urgent prioritization, tag Rick Winter (@RickWinter) and Kristen Womack (@kristenwomack) to let us know.

[Copilot]

🟡 Changes recommended

The specification may falsely fail equivalent access granted through custom roles.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

docs/specs/agent-doctor-storage-rbac/spec.md:17

• Restricting equivalent access to built-in roles would falsely fail a project whose managed identity receives the required blob data permissions through a custom role. Define this as effective access instead; the implementation should inspect role definitions and direct, inherited, or group assignments, and return WARN when effective access cannot be established.

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Balanced