fix(ci): cover .squad/agents charters, fix gate docs and test hygiene

Address review on bradygaster#1195:
- Add .squad/agents/*/charter.md to SDK_CLI_PATH_REGEX (final bradygaster#1156 bypass path)
- Correct the templates/ comment: append-only superset of .squad-templates/, not a full mirror
- Update CONTRIBUTING.md changeset-gate scope to match the widened gate
- Wrap the regex-presence assertion in beforeAll so YAML drift surfaces as a readable failure
- Extend the gate test with governed/unrelated .squad/agents cases

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

Author: obit91

.changeset/widen-changelog-gate-template-paths.md

@@ -4,4 +4,4 @@
 
 Widen changelog-gate coverage for template and scaffolding paths
 
-Previously, the changelog gate only required a changeset for `packages/squad-(sdk|cli)/src/` changes, so template and scaffolding updates under `packages/squad-(sdk|cli)/templates/`, `.squad-templates/`, and top-level `templates/` could reach users with no release-note entry. This widens the gate to those paths so user-facing template changes are no longer silently omitted from release notes. Closes #1156.
+Previously, the changelog gate only required a changeset for `packages/squad-(sdk|cli)/src/` changes, so template and scaffolding updates under `packages/squad-(sdk|cli)/templates/`, `.squad-templates/`, top-level `templates/`, and agent charters under `.squad/agents/*/charter.md` could reach users with no release-note entry. This widens the gate to those paths so user-facing template and scaffolding changes are no longer silently omitted from release notes. Closes #1156.

.github/workflows/squad-ci.yml

@@ -221,9 +221,10 @@ jobs:
           CHANGED=$(git diff --name-only "$BASE"..."$HEAD")
           # Paths whose changes ship behavioral or scaffolding updates and therefore
           # require a changeset (or CHANGELOG update). The top-level templates/ tree is
-          # a full canonical mirror of .squad-templates/ (see scripts/sync-templates.mjs),
-          # so the entire tree is governed squad scaffolding, not unrelated content.
-          SDK_CLI_PATH_REGEX='^packages/squad-(sdk|cli)/src/|^packages/squad-(sdk|cli)/templates/|^\.squad-templates/|^templates/'
+          # the primary sync target of .squad-templates/ (see scripts/sync-templates.mjs) —
+          # an append-only superset whose entire tree is governed squad scaffolding, not
+          # unrelated content. Agent charters under .squad/agents/ are likewise governed.
+          SDK_CLI_PATH_REGEX='^packages/squad-(sdk|cli)/src/|^packages/squad-(sdk|cli)/templates/|^\.squad-templates/|^templates/|^\.squad/agents/.+/charter\.md$'
           SDK_CLI_CHANGED=$(echo "$CHANGED" | grep -E "$SDK_CLI_PATH_REGEX" || true)
           if [ -z "$SDK_CLI_CHANGED" ]; then
             echo "✅ Not applicable (no SDK/CLI source or template changes)" >> $GITHUB_STEP_SUMMARY

CONTRIBUTING.md

@@ -187,7 +187,7 @@ External contributors don't have write access, so the review-to-merge flow has a
 
 **Your side (contributor):**
 
-1. ✅ All required CI checks are green (build, test, lint; changeset/CHANGELOG gate only applies when `packages/squad-cli/src/` or `packages/squad-sdk/src/` files change)
+1. ✅ All required CI checks are green (build, test, lint; the changeset/CHANGELOG gate applies when `packages/squad-(sdk|cli)/src/` **or** governed template/scaffolding paths change — `packages/squad-(sdk|cli)/templates/`, `.squad-templates/`, top-level `templates/`, and `.squad/agents/*/charter.md`)
 2. ✅ PR is no longer a draft — mark as **"Ready for review"**
 3. ✅ Copilot reviewer bot posts its review automatically
 4. ✅ Review Copilot's suggestions and manually apply any you agree with in your fork
@@ -214,7 +214,7 @@ An automated readiness check runs on every PR and posts a checklist comment. Add
 | **Not in draft** | Mark your PR as "Ready for review" when it's done |
 | **Branch up to date** | Rebase on latest `dev` (`git fetch upstream && git rebase upstream/dev`) |
 | **Copilot review** | Wait for the Copilot reviewer bot to post its review |
-| **Changeset present** | Run `npx changeset add` if you changed files in `packages/squad-sdk/src/` or `packages/squad-cli/src/` |
+| **Changeset present** | Run `npx changeset add` if you changed `packages/squad-(sdk|cli)/src/` or governed template/scaffolding paths (`packages/squad-(sdk|cli)/templates/`, `.squad-templates/`, top-level `templates/`, `.squad/agents/*/charter.md`) |
 | **No merge conflicts** | Resolve any conflicts with the target branch |
 | **CI passing** | All CI checks (build, test, lint) must be green |
 

test/ci/changelog-gate.test.ts

@@ -4,7 +4,7 @@
  * regressions in governed source/template paths.
  */
 
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeAll } from 'vitest';
 import { readFileSync } from 'node:fs';
 import path, { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -14,10 +14,15 @@ const workflowPath = path.resolve(__dirname, '..', '..', '.github', 'workflows',
 const workflow = readFileSync(workflowPath, 'utf-8');
 const patternMatch = workflow.match(/SDK_CLI_PATH_REGEX='([^']+)'/);
 
-expect(patternMatch, 'Expected changelog gate SDK_CLI_PATH_REGEX to be defined in squad-ci.yml').not.toBeNull();
+let regex: RegExp;
 
-const pattern = patternMatch?.[1] ?? '';
-const regex = new RegExp(pattern);
+beforeAll(() => {
+  expect(
+    patternMatch,
+    'Expected changelog gate SDK_CLI_PATH_REGEX to be defined in squad-ci.yml',
+  ).not.toBeNull();
+  regex = new RegExp(patternMatch?.[1] ?? '');
+});
 
 const governedPaths = [
   'packages/squad-sdk/src/index.ts',
@@ -28,6 +33,7 @@ const governedPaths = [
   '.squad-templates/scribe-charter.md',
   'templates/skills/release-process/SKILL.md',
   'templates/casting/policy.json',
+  '.squad/agents/troi/charter.md',
 ];
 
 const unrelatedPaths = [
@@ -38,6 +44,8 @@ const unrelatedPaths = [
   'packages/squad-cli/package.json',
   'scripts/bump-build.mjs',
   'test/ci/changelog-gate.test.ts',
+  '.squad/agents/troi/notes.md',
+  '.squad/routing.md',
 ];
 
 describe('changelog gate path matching', () => {