[#572] Implement Teams API Drift Detector workflow - Add metadata check

[ceciliaavila]

Addresses # 572

Description

This pull request introduces a comprehensive workflow and validation framework to ensure that changes to Microsoft Teams API usage and capability metadata are properly reviewed and acknowledged. It does so by updating the CI workflow, extending the drift tooling, documenting the review process, and adding automated tests for the new logic.

CI/CD and Metadata Validation Enhancements:

• New CI workflow for metadata validation:
  The main Python package workflow (.github/workflows/python-package.yml) now detects changes to MSTeams-relevant source or metadata files and conditionally runs a new validation job. This job checks if all relevant changes are properly reflected and acknowledged in the metadata files.

• Source review acknowledgment process:
  The documentation (scripts/teams-api-drift/README.md) now describes how to acknowledge source changes that do not require metadata updates. It introduces a structured way to record the outcome and reasoning for such acknowledgments in both teams-api-usage-manifest.json and teams-capabilities.yaml.

Tooling and Test Coverage Improvements:

• Drift tool enhancements:
  The drift tool (scripts/teams-api-drift/teams_api_drift/cli.py) and its underlying logic now support validating that source changes are accompanied by proper metadata updates or explicit acknowledgments, using a new --base-ref option to compare against the base branch. [1] [2] [3]

• Automated tests for metadata review logic:
  A new test suite (tests/teams_api_drift/test_metadata.py) covers scenarios such as unrecorded imports, missing or stale metadata, proper and improper review acknowledgments, and capability review requirements.

Capability Ownership Updates:

• Capability and ownership mapping updates:
  The Teams capabilities configuration (libraries/microsoft-agents-hosting-msteams/config/teams-capabilities.yaml) is updated to clarify ownership, add new owners for certain capabilities, and reference the new review acknowledgment process. [1] [2]

These changes together ensure that all relevant source and metadata changes are reviewed, acknowledged, and validated automatically, improving the reliability and maintainability of Teams API integrations.

Testing

These images show the CI workflow failing when issues are detected. And then passing after the issues are corrected.

[Copilot]

🟡 Changes recommended

The new workflow outputs use a hyphenated name (base-ref) that cannot be reliably referenced via dot notation in GitHub Actions expressions, which can break the metadata validation job.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR adds a Teams API “drift” metadata validation layer to ensure MSTeams source changes are either reflected in the usage/capabilities metadata or explicitly acknowledged via a documented review mechanism, and wires that validation into CI.

Changes:

• Added a new metadata validation implementation (validate_teams_api_metadata) and a dedicated test suite covering common failure/acknowledgment scenarios.
• Extended the drift CLI and documentation to support “source review acknowledgments” and a --base-ref mode for comparing against a base branch/commit.
• Updated CI (python-package.yml) to detect MSTeams-relevant changes and conditionally run the new metadata validation job, plus refreshed capability ownership mappings.

File summaries

File	Description
tests/teams_api_drift/test_metadata.py	New tests for the Teams API metadata validation + review acknowledgment behavior.
scripts/teams-api-drift/teams_api_drift/metadata.py	New validator that checks usage/capability metadata against source and (optionally) enforces “fresh review” vs a base ref.
scripts/teams-api-drift/teams_api_drift/cli.py	Hooks validator into verify-usage and adds --base-ref.
scripts/teams-api-drift/README.md	Documents the source review acknowledgment mechanism and local validation command.
libraries/microsoft-agents-hosting-msteams/config/teams-capabilities.yaml	Capability owner mapping updates + pointer to the new review docs.
.github/workflows/python-package.yml	Adds change detection + conditional metadata validation job in CI.

Review details

Suppressed comments (2)

.github/workflows/python-package.yml:53

• This step sets the output key as base-ref, but the workflow should use an underscore (base_ref) so it can be referenced reliably from steps.changed.outputs.* and needs.*.outputs.*.

        echo "base-ref=$base_ref" >> "$GITHUB_OUTPUT"

.github/workflows/python-package.yml:75

• This expression references outputs.base-ref, which won’t resolve due to the hyphenated output name. After renaming the output to base_ref, update this reference accordingly so the validator receives the base ref.

        BASE_REF: ${{ needs.teams-api-metadata-changes.outputs.base-ref }}

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

---

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