feat(ci): add path-based conditional CI and update copilot instructions

.cspell-repo-terms.txt

@@ -1,21 +1,29 @@
-AgentOS
-AgentMesh
 AgentGovernance
+AgentMesh
+AgentOS
+aioredis
 CMVK
+CrewAI
+Dify
+ESRP
+GitHub
 IATP
-Moltbook
-OpenClaw
-OpenAI
 LangChain
 LangGraph
 LlamaIndex
-CrewAI
-Dify
-SemanticKernel
-Microsoft
-GitHub
-workflow
-workflows
 markdown
+Microsoft
+Moltbook
+networkx
+OpenAI
+OpenClaw
+plotly
+pypdf
+pyproject
+SemanticKernel
+spacy
 spellcheck
 spellchecking
+streamlit
+workflow
+workflows

.github/copilot-instructions.md

@@ -1,40 +1,74 @@
 # Copilot Instructions for agent-governance-toolkit
 
+## PR Merge Workflow
+
+When merging PRs, follow this sequence for EACH PR (do not batch):
+
+1. **Review** — run all mandatory checks below
+2. **Update branch** — merge latest main into the PR branch (`update-branch` API or UI button)
+3. **Approve pending workflows** — fork PRs may have `pull_request_target` workflows waiting for maintainer approval; approve them in the Actions tab
+4. **Approve the PR** — submit an approving review
+5. **Enable auto-merge** — set squash auto-merge so it merges once CI passes
+6. **Move to next PR** — don't wait; auto-merge handles the rest
+
+This prevents PRs from stacking in the merge queue behind stale branches.
+
 ## PR Review — Mandatory Before Merge
 
 NEVER merge a PR without thorough code review. CI passing is NOT sufficient.
 
 Before approving or merging ANY PR, verify ALL of the following:
 
 1. **Read the actual diff** — don't rely on PR description alone
-2. **Dependency confusion scan** — check every `pip install`, `npm install` command in docs/code for unregistered package names. The registered names are: `agent-os-kernel`, `agentmesh-platform`, `agent-hypervisor`, `agentmesh-runtime`, `agent-sre`, `agent-governance-toolkit`, `agentmesh-lightning`, `agentmesh-marketplace`
+2. **Dependency confusion scan** — check every `pip install`, `npm install`, `cargo add` command in docs/code for unregistered package names. The registered names are:
+   - **PyPI:** `agent-os-kernel`, `agentmesh-platform`, `agent-hypervisor`, `agentmesh-runtime`, `agent-sre`, `agent-governance-toolkit`, `agentmesh-lightning`, `agentmesh-marketplace`
+   - **PyPI (local-only, not published):** `agent-governance-dotnet`, `agentmesh-integrations`, `agent-primitives`, `emk`
+   - **PyPI (common deps):** `streamlit`, `plotly`, `pandas`, `networkx`, `aioredis`, `pypdf`, `spacy`, `slack-sdk`, `docker`, `langchain-openai`
+   - **npm:** `@microsoft/agent-os-kernel`
+   - **crates.io:** `agentmesh`
 3. **New Python modules** — verify `__init__.py` exists in any new package directory
 4. **Dependencies declared** — any new `import` must have the package in `pyproject.toml` dependencies (not just transitive)
 5. **No hardcoded secrets** — no API keys, tokens, passwords, connection strings in code or docs
 6. **No plaintext config in pipelines** — ESRP Client IDs, Key Vault names, cert names go in secrets, not YAML
 7. **Verify PR has actual changes** — check `additions > 0` before merging (empty PRs have happened)
+8. **MIT license headers** — every new source file (`.py`, `.ts`, `.js`, `.rs`, `.go`, `.cs`, `.sh`) must have the license header. This is the #1 most common review finding.
 
 ## Security Rules
 
 - All `pip install` commands must reference registered PyPI packages
 - All security patterns must be in YAML config, not hardcoded
-- All GitHub Actions must be SHA-pinned
+- All GitHub Actions must be SHA-pinned (use `action@<sha> # vX.Y.Z` format, never bare tags like `@v46`)
 - All workflows must define `permissions:`
 - Use `yaml.safe_load()`, never `yaml.load()`
 - No `pickle.loads`, `eval()`, `exec()`, `shell=True` in production code
 - No `innerHTML` — use safe DOM APIs
+- No `unwrap()` in non-test Rust code paths (use `?` or explicit error handling)
+- Docker images must use pinned version tags or SHA digests (never `:latest`)
 
 ## Code Style
 
 - Use conventional commits (feat:, fix:, docs:, etc.)
 - Run tests before committing
-- MIT license headers on all source files
+- MIT license headers on all source files:
+  - Python/Shell: `# Copyright (c) Microsoft Corporation.\n# Licensed under the MIT License.`
+  - TypeScript/JavaScript/Rust/C#/Go: `// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT License.`
 - Author: Microsoft Corporation, email: agentgovtoolkit@microsoft.com
 - All packages prefixed with "Public Preview" in descriptions
 
+## CI Optimization
+
+CI workflows use path filters so only relevant checks run per PR:
+- **Python changes** (`packages/agent-mesh/`, `packages/agent-os/`, etc.) → lint + test for that package only
+- **TypeScript changes** (`sdks/typescript/`, `extensions/copilot/`) → TS lint + test only
+- **Rust changes** (`sdks/rust/`) → cargo test only
+- **.NET changes** (`agent-governance-dotnet/`) → dotnet test only
+- **Go changes** (`sdks/go/`) → go test only
+- **Docs-only changes** (`.md`, `notebooks/`) → link check only, skip all builds/tests
+- **Workflow changes** (`.github/workflows/`) → workflow-security audit only
+
 ## Publishing
 
-- PyPI/npm/NuGet publishing goes through ESRP Release (ADO pipelines), NOT GitHub Actions
+- PyPI/npm/NuGet/crates.io publishing goes through ESRP Release (ADO pipelines), NOT GitHub Actions
 - All ESRP config values must be in pipeline secrets, never plaintext in YAML
 - Package names must NOT start with `microsoft` or `windows` (reserved by Python team)
 - npm packages use `@microsoft` scope only

.github/workflows/cflite.yml

@@ -3,8 +3,14 @@ name: ClusterFuzzLite
 on:
   push:
     branches: [main]
+    paths:
+      - 'packages/*/src/**'
+      - 'fuzz/**'
   pull_request:
     branches: [main]
+    paths:
+      - 'packages/*/src/**'
+      - 'fuzz/**'
   schedule:
     - cron: "0 6 * * 0"  # Weekly batch fuzzing
 

.github/workflows/ci.yml

@@ -10,7 +10,50 @@ permissions:
   contents: read
 
 jobs:
+  # ── Path detection — determines which jobs to run ─────────────────────
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      python: ${{ steps.filter.outputs.python }}
+      dotnet: ${{ steps.filter.outputs.dotnet }}
+      typescript: ${{ steps.filter.outputs.typescript }}
+      integrations: ${{ steps.filter.outputs.integrations }}
+      workflows: ${{ steps.filter.outputs.workflows }}
+      docs-only: ${{ steps.filter.outputs.docs-only }}
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          filters: |
+            python:
+              - 'packages/agent-os/**'
+              - 'packages/agent-mesh/**'
+              - 'packages/agent-hypervisor/**'
+              - 'packages/agent-sre/**'
+              - 'packages/agent-compliance/**'
+              - 'scripts/**'
+              - 'requirements/**'
+            dotnet:
+              - 'packages/agent-governance-dotnet/**'
+            typescript:
+              - 'packages/agent-mesh/sdks/typescript/**'
+              - 'packages/agent-os/extensions/**'
+              - 'packages/agentmesh-integrations/mastra-agentmesh/**'
+              - 'packages/agentmesh-integrations/copilot-governance/**'
+            integrations:
+              - 'packages/agentmesh-integrations/**'
+            workflows:
+              - '.github/workflows/**'
+            docs-only:
+              - '**/*.md'
+              - 'notebooks/**'
+              - 'docs/**'
+
+  # ── Python lint + test (only when Python files change) ────────────────
   lint:
+    needs: changes
+    if: needs.changes.outputs.python == 'true'
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -25,7 +68,10 @@ jobs:
       - name: Lint ${{ matrix.package }}
         run: ruff check packages/${{ matrix.package }}/src/ --select E,F,W --ignore E501
 
+  # ── Python test (only when Python files change) ───────────────────────
   test:
+    needs: changes
+    if: needs.changes.outputs.python == 'true'
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -46,7 +92,10 @@ jobs:
         working-directory: packages/${{ matrix.package }}
         run: pytest tests/ -q --tb=short
 
+  # ── Python dependency safety (only when Python files change) ──────────
   security:
+    needs: changes
+    if: needs.changes.outputs.python == 'true'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -68,7 +117,10 @@ jobs:
           done
           safety check 2>/dev/null || echo "Safety check completed with warnings"
 
+  # ── .NET build + test (only when C# files change) ────────────────────
   test-dotnet:
+    needs: changes
+    if: needs.changes.outputs.dotnet == 'true'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -82,7 +134,10 @@ jobs:
         working-directory: packages/agent-governance-dotnet
         run: dotnet test --configuration Release --verbosity normal --no-build
 
+  # ── Integration tests (only when integration packages change) ────────
   test-integrations:
+    needs: changes
+    if: needs.changes.outputs.integrations == 'true' || needs.changes.outputs.python == 'true'
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -153,6 +208,7 @@ jobs:
             echo "No tests/ directory — smoke import passed"
           fi
 
+  # ── Dependency confusion scan (always runs — security gate) ──────────
   dependency-scan:
     runs-on: ubuntu-latest
     steps:
@@ -204,7 +260,10 @@ jobs:
           print(f'OK: All notebook pip install packages are registered')
           "
 
+  # ── Workflow security audit (only when workflows change) ─────────────
   workflow-security:
+    needs: changes
+    if: needs.changes.outputs.workflows == 'true'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -226,7 +285,10 @@ jobs:
           done
           if [ $UNSAFE -eq 1 ]; then exit 1; fi
 
+  # ── TypeScript integration tests (only when TS files change) ─────────
   test-integrations-ts:
+    needs: changes
+    if: needs.changes.outputs.typescript == 'true'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -251,3 +313,23 @@ jobs:
       - name: Test copilot-governance
         working-directory: packages/agentmesh-integrations/copilot-governance
         run: npm test
+
+  # ── CI Gate — required status check that handles skipped jobs ────────
+  # When path-filters skip jobs (e.g. docs-only PRs skip tests), those
+  # jobs report "skipped" which doesn't satisfy required status checks.
+  # This gate job always runs, checks that no jobs FAILED, and reports
+  # success. Configure this as the single required status check.
+  ci-complete:
+    if: always()
+    needs: [changes, lint, test, security, test-dotnet, test-integrations, dependency-scan, workflow-security, test-integrations-ts]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check job results
+        run: |
+          results='${{ toJSON(needs.*.result) }}'
+          echo "Job results: $results"
+          if echo "$results" | grep -qE '"failure"|"cancelled"'; then
+            echo "One or more required jobs failed or were cancelled"
+            exit 1
+          fi
+          echo "All jobs passed or were correctly skipped"

.github/workflows/security-scan.yml

@@ -3,8 +3,16 @@ name: Security Scan
 on:
   push:
     branches: [main]
+    paths:
+      - 'packages/**'
+      - 'scripts/**'
+      - 'requirements/**'
   pull_request:
     branches: [main]
+    paths:
+      - 'packages/**'
+      - 'scripts/**'
+      - 'requirements/**'
 
 permissions:
   contents: read