feat: add 10 AI-powered GitHub Actions workflows (#294)

Add AI agent workflows for the governance toolkit:

PR Quality:
- ai-code-review.yml — Deep review for policy/trust/sandbox code
- ai-security-scan.yml — Security analysis (OWASP Agentic Top 10)
- ai-test-generator.yml — Test coverage advisor for 8 packages
- ai-breaking-change-detector.yml — Public API compatibility check
- ai-docs-sync.yml — Documentation freshness check

Scheduled:
- ai-repo-health.yml — Weekly OSS health dashboard
- ai-owasp-compliance.yml — Weekly OWASP Agentic Top 10 audit

Release:
- ai-release-notes.yml — Monorepo-aware changelog by package

Community:
- ai-contributor-guide.yml — First-time contributor helper
- ai-spec-drafter.yml — Engineering spec from issues

All workflows use GitHub Models API (gpt-4o) via GITHUB_TOKEN
with models:read permission. Action SHAs are pinned per OSS
security best practices. PR-triggered AI jobs are non-blocking.

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

Author: imran-siddique

.github/actions/ai-agent-runner/action.yml

@@ -0,0 +1,75 @@
+# AI-powered breaking change detector for the agent-governance-toolkit.
+# Critical for published PyPI packages — detects removed/renamed public APIs,
+# changed function signatures, modified exports in __init__.py, and changed
+# exception types. Posts findings as a PR comment with severity ratings.
+name: AI Breaking Change Detector
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches: [main]
+    paths:
+      - "packages/*/src/**"
+
+permissions:
+  contents: read
+  pull-requests: write
+  models: read
+
+jobs:
+  detect-breaking-changes:
+    name: API Compatibility Check
+    runs-on: ubuntu-latest
+    if: >-
+      github.event.pull_request.draft == false &&
+      github.actor != 'dependabot[bot]' &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Run breaking change analysis
+        uses: ./.github/actions/ai-agent-runner
+        with:
+          agent-type: breaking-change-detector
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          model: gpt-4o
+          fallback-model: gpt-4o-mini
+          max-tokens: "4000"
+          context-mode: pr-diff
+          output-mode: pr-comment
+          custom-instructions: |
+            You are an API compatibility analyzer for microsoft/agent-governance-toolkit.
+            These packages are published to PyPI — breaking changes affect downstream users.
+
+            Analyze the diff for:
+            1. **🔴 Removed/renamed** public functions, classes, or methods
+            2. **🔴 Changed function signatures** — removed params, changed types, new required params
+            3. **🔴 Removed/changed exports** in `__init__.py` files
+            4. **🔴 Changed exception types** — different exceptions raised
+            5. **🟡 Changed default values** — may alter existing behavior
+            6. **🟡 Changed return types** — may break callers
+            7. **🔵 New public API** — not breaking, but should be documented
+
+            Classification:
+            - 🔴 **BREAKING** — will break existing code
+            - 🟡 **POTENTIALLY BREAKING** — may break depending on usage
+            - 🔵 **ADDITIVE** — new API, not breaking
+
+            If NO breaking changes found, say so clearly with ✅.
+
+            Format:
+            ## 🔍 API Compatibility Report
+
+            ### Summary
+            (brief overall assessment)
+
+            ### Findings
+            | Severity | Package | Change | Impact |
+            |----------|---------|--------|--------|
+            | 🔴 | agent-os | `PolicyEngine.evaluate()` removed `strict` param | Callers using `strict=True` will fail |
+
+            ### Migration Guide
+            (if breaking changes found, suggest migration steps)

.github/workflows/ai-breaking-change-detector.yml

@@ -0,0 +1,60 @@
+# AI-powered deep code review for the agent-governance-toolkit.
+# Analyzes PR diffs for security issues, policy engine correctness,
+# trust/identity flaws, sandbox escape vectors, and API compatibility.
+# Uses GitHub Models API (gpt-4o) via the ai-agent-runner composite action.
+name: AI Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+  models: read
+
+jobs:
+  ai-review:
+    name: Deep AI Code Review
+    runs-on: ubuntu-latest
+    # Skip bots, draft PRs, and fork PRs (security: don't run on untrusted code)
+    if: >-
+      github.event.pull_request.draft == false &&
+      github.actor != 'dependabot[bot]' &&
+      github.actor != 'github-actions[bot]' &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Run AI code review
+        id: review
+        uses: ./.github/actions/ai-agent-runner
+        with:
+          agent-type: code-reviewer
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          model: gpt-4o
+          fallback-model: gpt-4o-mini
+          max-tokens: "4000"
+          context-mode: pr-diff
+          output-mode: pr-review
+          custom-instructions: |
+            You are reviewing the microsoft/agent-governance-toolkit — a security-focused Python library.
+
+            Stack: Python 3.9-3.12, monorepo with 8 packages under packages/, pytest, ruff.
+
+            Focus areas:
+            - Policy engine correctness (false negatives = security bypass)
+            - Trust/identity: cryptographic operations, credential handling, SPIFFE/SVID
+            - Sandbox escape vectors
+            - Thread safety in concurrent agent execution
+            - OWASP Agentic Top 10 compliance
+            - Type safety and Pydantic model validation
+            - Backward compatibility (public API changes)
+
+            Provide actionable feedback. Flag security issues as 🔴 CRITICAL.
+            Flag potential breaking changes as 🟡 WARNING.
+            Suggest improvements as 💡 SUGGESTION.

.github/workflows/ai-code-review.yml

@@ -0,0 +1,109 @@
+# AI-powered contributor helper for the agent-governance-toolkit.
+# Welcomes first-time contributors with helpful, personalized context:
+# - For issues: analyzes the issue and suggests relevant packages/code areas
+# - For PRs: provides a friendly first-PR review with extra guidance
+# Builds OSS community by making the contribution experience welcoming.
+name: AI Contributor Guide
+
+on:
+  issues:
+    types: [opened]
+  pull_request_target:
+    types: [opened]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+  models: read
+
+jobs:
+  guide-issue:
+    name: Guide First-Time Issue Author
+    runs-on: ubuntu-latest
+    # Only trigger for first-time contributors (never seen before or first contribution)
+    if: >-
+      github.event_name == 'issues' &&
+      (github.event.issue.author_association == 'NONE' ||
+       github.event.issue.author_association == 'FIRST_TIME_CONTRIBUTOR')
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Guide contributor on issue
+        uses: ./.github/actions/ai-agent-runner
+        with:
+          agent-type: contributor-guide
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          model: gpt-4o
+          fallback-model: gpt-4o-mini
+          max-tokens: "4000"
+          context-mode: issue
+          output-mode: issue-comment
+          custom-instructions: |
+            You are a friendly OSS community helper for microsoft/agent-governance-toolkit.
+            A first-time contributor has opened an issue. Welcome them warmly!
+
+            Your response should:
+            1. **Welcome** them to the project
+            2. **Analyze** their issue and suggest which package(s) might be relevant:
+               - agent-os: Core policy engine, agent lifecycle
+               - agent-mesh: Agent discovery, routing, trust mesh
+               - agent-hypervisor: Execution sandboxing, resource isolation
+               - agent-sre: Reliability, chaos testing, SLOs
+               - agent-compliance: Compliance frameworks, audit logging
+               - agent-marketplace: Agent registry
+               - agent-lightning: High-performance inference
+               - agent-runtime: Runtime execution environment
+            3. **Point to relevant code** — suggest specific directories to look at
+            4. **Link to resources**:
+               - [CONTRIBUTING.md](../blob/main/CONTRIBUTING.md)
+               - [QUICKSTART.md](../blob/main/QUICKSTART.md)
+               - [Code of Conduct](../blob/main/CODE_OF_CONDUCT.md)
+            5. **Offer next steps** — what they can do to help resolve this
+
+            Be encouraging and specific. Avoid generic boilerplate.
+
+  guide-pr:
+    name: Guide First-Time PR Author
+    runs-on: ubuntu-latest
+    # Only trigger for first-time contributors on PRs
+    # Uses pull_request_target for security (runs on base branch context)
+    if: >-
+      github.event_name == 'pull_request_target' &&
+      (github.event.pull_request.author_association == 'NONE' ||
+       github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR')
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Guide PR author
+        uses: ./.github/actions/ai-agent-runner
+        with:
+          agent-type: contributor-guide
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          model: gpt-4o
+          fallback-model: gpt-4o-mini
+          max-tokens: "4000"
+          context-mode: pr-diff
+          output-mode: pr-comment
+          custom-instructions: |
+            You are a friendly OSS community helper for microsoft/agent-governance-toolkit.
+            A first-time contributor has opened a pull request. Welcome them!
+
+            Your response should:
+            1. **Welcome** them and thank them for contributing
+            2. **Review their PR** with extra kindness — explain WHY things should be
+               different, not just what to change
+            3. **Highlight what they did well** before suggesting improvements
+            4. **Explain project conventions**:
+               - We use ruff for linting (select E,F,W)
+               - Tests go in packages/{name}/tests/
+               - We follow conventional commits (feat:, fix:, docs:, etc.)
+               - Security-sensitive code gets extra scrutiny
+            5. **Link to resources**:
+               - [CONTRIBUTING.md](../blob/main/CONTRIBUTING.md)
+               - [QUICKSTART.md](../blob/main/QUICKSTART.md)
+            6. **Explain next steps** — what happens in the review process
+
+            Be warm, specific, and constructive. First impressions matter for OSS!

.github/workflows/ai-contributor-guide.yml

@@ -0,0 +1,75 @@
+# AI-powered documentation freshness check for agent-governance-toolkit.
+# When a PR touches package source code, verifies that corresponding
+# documentation is updated — flags missing docstrings, stale READMEs,
+# and changed behavior without CHANGELOG entries.
+name: AI Docs Sync Check
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches: [main]
+    paths:
+      - "packages/*/src/**"
+
+permissions:
+  contents: read
+  pull-requests: write
+  models: read
+
+jobs:
+  docs-freshness:
+    name: Documentation Freshness Check
+    runs-on: ubuntu-latest
+    if: >-
+      github.event.pull_request.draft == false &&
+      github.actor != 'dependabot[bot]' &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Check documentation freshness
+        uses: ./.github/actions/ai-agent-runner
+        with:
+          agent-type: docs-sync-checker
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          model: gpt-4o
+          fallback-model: gpt-4o-mini
+          max-tokens: "4000"
+          context-mode: pr-diff
+          output-mode: pr-comment
+          custom-instructions: |
+            You are a documentation freshness checker for microsoft/agent-governance-toolkit.
+
+            Analyze the PR diff and check:
+            1. **New public APIs without docstrings** — all public functions, classes, and
+               methods should have docstrings explaining purpose, parameters, return values,
+               and exceptions
+            2. **README sections out of date** — if behavior changes, does the package README
+               reflect it?
+            3. **CHANGELOG missing entries** — behavioral changes should have a CHANGELOG.md entry
+            4. **Example code outdated** — if API signatures change, examples/ should be updated
+            5. **Type hints** — new public APIs should have complete type annotations
+
+            Monorepo structure:
+            - packages/{name}/src/ — source code
+            - packages/{name}/README.md — package documentation
+            - packages/{name}/tests/ — test files
+            - docs/ — project-level documentation
+            - CHANGELOG.md — project changelog
+
+            Format:
+            ## 📝 Documentation Sync Report
+
+            ### Issues Found
+            - ❌ `function_name()` in `package/module.py` — missing docstring
+            - ⚠️ `package/README.md` — section X may need update for new behavior
+            - ⚠️ CHANGELOG.md — no entry for this change
+
+            ### Suggestions
+            - 💡 Add docstring for `function_name(param1: str, param2: int) -> bool`
+            - 💡 Update README section "Configuration" to mention new option
+
+            If everything looks good, say ✅ Documentation is in sync.