From 834e9a2458760f1fddd662c0dfa309c133c6fac7 Mon Sep 17 00:00:00 2001
From: Conal <33135619+Conalh@users.noreply.github.com>
Date: Thu, 21 May 2026 18:46:18 -0700
Subject: [PATCH] Add team pilot validation guide

---
 README.md              |  1 +
 docs/TEAM_PILOT.md     | 55 ++++++++++++++++++++++++++++++++++++++++++
 test/workflow.test.mjs |  9 +++++++
 3 files changed, 65 insertions(+)
 create mode 100644 docs/TEAM_PILOT.md

diff --git a/README.md b/README.md
index 61fe57e..f93bd5f 100644
--- a/README.md
+++ b/README.md
@@ -162,6 +162,7 @@ If your team uses another agent config surface, open a
 If your team is testing PolicyMesh across multiple repositories, needs org-level
 policy review, shared baselines, exception ownership, or cross-repo reports, open a
 [team validation signal](https://github.com/Conalh/PolicyMesh/issues/new?template=team-validation.yml).
+For a concrete multi-repo trial path, use the [team pilot guide](docs/TEAM_PILOT.md).
 The paid-layer validation tracker is
 [issue #5](https://github.com/Conalh/PolicyMesh/issues/5); hosted SaaS work should wait for repeated team signals there.
 
diff --git a/docs/TEAM_PILOT.md b/docs/TEAM_PILOT.md
new file mode 100644
index 0000000..10beee7
--- /dev/null
+++ b/docs/TEAM_PILOT.md
@@ -0,0 +1,55 @@
+# PolicyMesh Team Pilot
+
+Use this when a team wants to validate whether the free GitHub Action is enough before any paid team layer or hosted SaaS work is built.
+
+## Pilot Setup
+
+Run across at least two repositories that use AI-agent configuration in normal pull requests. Start advisory so the pilot measures signal quality without blocking developers.
+
+```yaml
+name: PolicyMesh
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  policymesh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: Conalh/PolicyMesh@v0.1.18
+        with:
+          fail-on: none
+```
+
+Keep the workflow unchanged for the first pass unless the repository needs the `repo` input for a subdirectory audit.
+
+## What To Record
+
+For each repository, record:
+
+- Active surfaces: root MCP, Cursor MCP, VS Code MCP, Codeium MCP, Windsurf MCP, Claude settings, Codex settings, and Codex MCP tables.
+- Finding counts by severity from the Action summary.
+- Whether annotations point at the file and line the team would actually review.
+- Whether each warning is actionable, noisy, or missing important context.
+- Whether advisory mode is enough or a stricter `fail-on` threshold would be used after tuning.
+
+## Paid-Layer Signals
+
+Do not treat a single warning as paid-layer validation. Paid-layer work needs repeated team needs that the free Action and repo-local workflow config cannot solve.
+
+Useful validation signals include:
+
+- shared baselines or defaults that multiple repositories should inherit;
+- central severity policy that cannot be managed in each repo workflow;
+- exception ownership, expiry, approval, or review history;
+- cross-repo reports, audit exports, or dashboard/API needs;
+- a blocker that prevents trying PolicyMesh in pull requests even with `fail-on: none`.
+
+## Report Back
+
+Open a [team validation signal](https://github.com/Conalh/PolicyMesh/issues/new?template=team-validation.yml) with the repository count, active surfaces, finding patterns, and any paid-layer need. The paid-layer tracker remains [issue #5](https://github.com/Conalh/PolicyMesh/issues/5).
diff --git a/test/workflow.test.mjs b/test/workflow.test.mjs
index e1f9110..9012bbd 100644
--- a/test/workflow.test.mjs
+++ b/test/workflow.test.mjs
@@ -97,6 +97,7 @@ test('issue templates collect detector and team validation feedback', async () =
   const missingSurface = await readFile(join(packageRoot, '.github', 'ISSUE_TEMPLATE', 'missing-surface.yml'), 'utf8');
   const teamValidation = await readFile(join(packageRoot, '.github', 'ISSUE_TEMPLATE', 'team-validation.yml'), 'utf8');
   const readme = await readFile(join(packageRoot, 'README.md'), 'utf8');
+  const teamPilot = await readFile(join(packageRoot, 'docs', 'TEAM_PILOT.md'), 'utf8');
 
   assert.match(falsePositive, /repository-count/);
   assert.match(missingSurface, /Review surface/);
@@ -108,6 +109,14 @@ test('issue templates collect detector and team validation feedback', async () =
   assert.match(teamValidation, /Reporting or export need/);
   assert.match(teamValidation, /Team workflow/);
   assert.match(teamValidation, /Paid-layer signal/);
+  assert.match(teamPilot, /Conalh\/PolicyMesh@v0\.1\.18/);
+  assert.match(teamPilot, /Run across at least two repositories/);
+  assert.match(teamPilot, /Finding counts by severity/);
+  assert.match(teamPilot, /shared baselines/);
+  assert.match(teamPilot, /exception ownership/);
+  assert.match(teamPilot, /cross-repo reports/);
+  assert.match(teamPilot, /team-validation\.yml/);
+  assert.match(readme, /TEAM_PILOT\.md/);
   assert.match(readme, /team-validation\.yml/);
   assert.match(readme, /issues\/5/);
 });