chore(scripts): add cross-layer frontmatter parity check to check_agents (#741)

check_agents.sh and its PowerShell twin previously stripped frontmatter and compared only the agent bodies, so the permissionMode layer drift fixed in #729 shipped silently. Add a parity check on the behavioral frontmatter fields tools and permissionMode across the plugin and project copies (fail with exit 2 on mismatch); color stays exempt as an intended project-only field. Adds regression cases (tools drift, permissionMode drift, color-only diff) and updates the CUSTOM_EXTENSIONS.md CI-enforcement note.

Author: kcenon

docs/CUSTOM_EXTENSIONS.md

@@ -212,7 +212,7 @@ pwsh scripts/sync_references.ps1   # Windows
 
 The eight agent definitions exist in two layers — `project/.claude/agents/` and the standalone `plugin/agents/` bundle. They are near-duplicates but **not** byte-identical by design: frontmatter differs per layer (the project copy carries `color:`; neither carries the non-canonical `temperature:` field; `permissionMode: acceptEdits` is kept identical across both layers for the two write agents, documentation-writer and refactor-assistant), and the body genericizes exactly one repo-specific "language-specific rules" sentence in the plugin copy.
 
-**CI enforcement**: `.github/workflows/validate-skills.yml` runs `scripts/check_agents.sh` (PowerShell twin: `scripts/check_agents.ps1`). It strips frontmatter and normalizes that single sentence, then fails (exit 2) if the agent **bodies** otherwise diverge — so a behavioral instruction edited in one layer but not the other cannot ship silently.
+**CI enforcement**: `.github/workflows/validate-skills.yml` runs `scripts/check_agents.sh` (PowerShell twin: `scripts/check_agents.ps1`). It strips frontmatter and normalizes that single sentence, then fails (exit 2) if the agent **bodies** otherwise diverge, or if the behavioral frontmatter fields `tools` or `permissionMode` differ between layers (intended per-layer fields like `color` are exempt) — so a behavioral instruction or capability edited in one layer but not the other cannot ship silently.
 
 **Advisory frontmatter (`applies_to`, `keywords`)**: every agent declares `applies_to` (a glob list) and `keywords`. These are **not** official Claude Code runtime path-triggers — the runtime delegates to a sub-agent only by its `description`. They are advisory inputs consumed by the `fleet-orchestrator` skill's Top-K routing score (`score = 2 * matched_applies_to_globs + 1 * matched_keywords`, see `global/skills/_internal/fleet-orchestrator/SKILL.md`). Opening a file that matches an `applies_to` glob does **not** auto-invoke the agent; keep delegation intent in `description`.
 

scripts/check_agents.ps1

@@ -3,7 +3,9 @@
 # Drift guard for the 8 agent definitions duplicated across plugin/agents/
 # and project/.claude/agents/. See check_agents.sh for the full rationale:
 # frontmatter differs per layer and one repo-path sentence is genericized in
-# the plugin copy; the bodies must otherwise stay identical.
+# the plugin copy; the bodies must otherwise stay identical. In addition the
+# behavioral frontmatter fields `tools` and `permissionMode` must match across
+# layers (intended per-layer fields like `color` are exempt).
 # Exit: 0 = in sync, 2 = drift.
 
 $ErrorActionPreference = 'Stop'
@@ -39,6 +41,25 @@ function Get-NormalizedBody {
     return ($body -join "`n")
 }
 
+# Extract the value of a frontmatter key from the first '---' block. Returns
+# the empty string when the key is absent, so a key declared on only one layer
+# surfaces as a drift.
+function Get-FrontmatterField {
+    param([string]$Path, [string]$Key)
+    $dashes = 0
+    foreach ($line in (Get-Content -LiteralPath $Path -Encoding utf8)) {
+        if ($line -eq '---') {
+            $dashes++
+            if ($dashes -ge 2) { break }
+            continue
+        }
+        if ($dashes -eq 1 -and $line -match ('^' + [regex]::Escape($Key) + ':')) {
+            return ($line -replace ('^' + [regex]::Escape($Key) + ':\s*'), '').TrimEnd()
+        }
+    }
+    return ''
+}
+
 $drift = 0
 foreach ($a in $Agents) {
     $p = Join-Path $RootDir "plugin/agents/$a.md"
@@ -49,10 +70,21 @@ foreach ($a in $Agents) {
         Write-Host "FAIL: agent body drift: plugin/agents/$a.md vs project/.claude/agents/$a.md"
         $drift = 1
     }
+
+    # Behavioral frontmatter parity: layers may differ in declarative fields
+    # (color, model, ...) but must agree on what the agent can do.
+    foreach ($field in @('tools', 'permissionMode')) {
+        $pv = Get-FrontmatterField $p $field
+        $cv = Get-FrontmatterField $c $field
+        if ($pv -ne $cv) {
+            Write-Host "FAIL: frontmatter '$field' drift for $($a): plugin='$pv' project='$cv'"
+            $drift = 1
+        }
+    }
 }
 
 if ($drift -eq 0) {
-    Write-Host "check_agents: OK ($($Agents.Count) agent pairs in sync)"
+    Write-Host "check_agents: OK ($($Agents.Count) agent pairs: bodies + behavioral frontmatter in sync)"
     exit 0
 }
 

scripts/check_agents.sh

@@ -15,6 +15,14 @@
 # near-duplicate pair cannot silently diverge (e.g. a behavioral instruction
 # edited in one copy but not the other).
 #
+# In addition, the two BEHAVIORAL frontmatter fields `tools` and
+# `permissionMode` must match across layers: they change what a sub-agent is
+# allowed to do, so a per-layer divergence (such as the #729 permissionMode
+# drift) is a real defect, not an intended per-layer difference. Intended
+# per-layer fields (`color`, plus declarative ones like `model`/`maxTurns`/
+# `effort`/`memory`/`applies_to`/`keywords`/`initialPrompt`) are deliberately
+# NOT compared, so future intended per-layer diffs are not blocked.
+#
 # Reference drift is intentionally NOT guarded here: the plugin skill
 # reference tree is a curated RE-STRUCTURING of rules/ (content is split and
 # recombined across files, e.g. observability -> observability + logging), so
@@ -46,6 +54,24 @@ strip_and_norm() {
         | sed -E 's/^If .*language-specific rules.*read them before starting\.$/<RULES_PATH_NOTE>/'
 }
 
+# Extract the value of a frontmatter key (e.g. `tools`, `permissionMode`) from
+# the first '---' block of an agent file. Matches `^<key>:` only inside the
+# frontmatter, trims surrounding whitespace, and prints the empty string when
+# the key is absent (so a key declared on one layer but not the other surfaces
+# as a drift).
+frontmatter_field() {
+    awk -v key="$2" '
+        BEGIN { f = 0 }
+        /^---$/ { f++; if (f >= 2) exit; next }
+        f == 1 && $0 ~ "^" key ":" {
+            sub("^" key ":[ \t]*", "")
+            sub(/[ \t]+$/, "")
+            print
+            exit
+        }
+    ' "$1"
+}
+
 drift=0
 for a in "${AGENTS[@]}"; do
     p="$ROOT_DIR/plugin/agents/$a.md"
@@ -59,15 +85,27 @@ for a in "${AGENTS[@]}"; do
         diff <(strip_and_norm "$p") <(strip_and_norm "$c") 2>/dev/null | sed 's/^/    /' >&2 || true
         drift=1
     fi
+
+    # Behavioral frontmatter parity: the layers may differ in declarative
+    # fields (color, model, ...) but must agree on what the agent can do.
+    for field in tools permissionMode; do
+        pv="$(frontmatter_field "$p" "$field")"
+        cv="$(frontmatter_field "$c" "$field")"
+        if [ "$pv" != "$cv" ]; then
+            echo "FAIL: frontmatter '$field' drift for $a: plugin='$pv' project='$cv'" >&2
+            drift=1
+        fi
+    done
 done
 
 if [ "$drift" -eq 0 ]; then
-    echo "check_agents: OK (${#AGENTS[@]} agent pairs in sync)"
+    echo "check_agents: OK (${#AGENTS[@]} agent pairs: bodies + behavioral frontmatter in sync)"
     exit 0
 fi
 
 echo "" >&2
 echo "check_agents: drift detected between plugin/agents and project/.claude/agents." >&2
-echo "The body content must match (frontmatter and the single rules-path" >&2
-echo "sentence may differ by design). Reconcile the divergent lines above." >&2
+echo "The body content and the behavioral frontmatter fields ('tools',"  >&2
+echo "'permissionMode') must match. Other frontmatter (e.g. 'color') and the"  >&2
+echo "single rules-path sentence may differ by design. Reconcile the lines above." >&2
 exit 2

tests/scripts/test-check-agents.sh

@@ -63,6 +63,39 @@ sed -i 's|^If .*language-specific rules.*read them before starting\.$|If any lan
 assert_exit 0 $rc "rules-path sentence variant -> exit 0"
 rm -rf "$sb"
 
+# Portable in-place replace: BSD sed (macOS) needs `-i ''` while GNU sed
+# (Linux/CI) rejects the empty arg, so use a temp file + mv that works on both.
+replace_in_file() {
+    local pattern="$1" file="$2" tmp
+    tmp="$(mktemp)"
+    sed "$pattern" "$file" > "$tmp" && mv "$tmp" "$file"
+}
+
+# 5. A `tools` frontmatter divergence in one layer is flagged.
+sb=$(mktemp -d); mk_sandbox "$sb"
+replace_in_file 's|^tools: Read, Grep, Glob, Bash$|tools: Read, Grep, Glob, Bash, Write|' \
+    "$sb/plugin/agents/qa-reviewer.md"
+( cd "$sb" && bash scripts/check_agents.sh >/dev/null 2>&1 ); rc=$?
+assert_exit 2 $rc "tools frontmatter drift -> exit 2"
+rm -rf "$sb"
+
+# 6. A `permissionMode` frontmatter divergence in one layer is flagged.
+sb=$(mktemp -d); mk_sandbox "$sb"
+replace_in_file 's|^permissionMode: acceptEdits$|permissionMode: bypassPermissions|' \
+    "$sb/project/.claude/agents/documentation-writer.md"
+( cd "$sb" && bash scripts/check_agents.sh >/dev/null 2>&1 ); rc=$?
+assert_exit 2 $rc "permissionMode frontmatter drift -> exit 2"
+rm -rf "$sb"
+
+# 7. An intended per-layer frontmatter field (color) is tolerated even when it
+#    differs — the guard only compares `tools` and `permissionMode`.
+sb=$(mktemp -d); mk_sandbox "$sb"
+replace_in_file 's|^color: .*$|color: magenta|' \
+    "$sb/project/.claude/agents/qa-reviewer.md"
+( cd "$sb" && bash scripts/check_agents.sh >/dev/null 2>&1 ); rc=$?
+assert_exit 0 $rc "color-only frontmatter diff -> exit 0"
+rm -rf "$sb"
+
 echo ""
 echo "=== Results: $PASS passed, $FAIL failed ==="
 if [ ${#ERRORS[@]} -gt 0 ]; then