perf(ci): short-circuit plugin-gate and miro-plugin on docs-only diffs (#617)

[kyle-sexton]

Closes #617

Summary

Docs-only PRs — operator precedent codifications and other docs/topics/ churn, a large share of current throughput per #617 — ran the full plugin contract suite (plugin-gate: Node + Python installs, every plugins/**/*.test.sh, manifest + catalog validation) and the full miro-plugin Node build for a diff that cannot affect either. Both lanes now short-circuit their expensive steps when the diff is confined to a small, positive, provably-inert allowlist, reporting an honest evaluated-and-not-applicable success.

Fix

Mechanism — in-job detection, never a job skip. GitHub's docs are explicit: "If a workflow is skipped due to path filtering, branch filtering or a commit message, then checks associated with that workflow will remain in a 'Pending' state. A pull request that requires those checks to be successful will be blocked from merging." whereas "If, however, a job within a workflow is skipped due to a conditional, it will report its status as 'Success.'" (troubleshooting-required-status-checks). So workflow-level paths:/paths-ignore: is ruled out for required checks. It is doubly ruled out here: the sole required check is the ci-status aggregate, which fails unless every lane's result is exactly success — a conditionally-skipped job's result is skipped, not success, so even a job-level if: would red the aggregate. The safe pattern is therefore the one #593/#609 already use: the job always runs, self-tests its detector first, and gates only its inner expensive steps, staying success and reporting to branch protection either way.

New files:

• scripts/check-docs-only.sh — emits docs_only=true|false to $GITHUB_OUTPUT; true iff every path changed vs the base ref matches an allowlist prefix. Fail-closed toward running the full suite: an unresolvable base ref, an empty/missing allowlist, or an empty diff all emit false with a stderr note and exit 0 (a code PR is not an error — "has code" is never encoded as a non-zero exit that would red every code PR).
• scripts/docs-only-paths.txt — the allowlist as external, extensible data (same shape as feat(ci): add portability-lint gate for ecosystem/forge-agnostic skills (#531) #609's token list). Allowlist, not blocklist, by design: a blocklist ("skip on any doc the validators don't currently read") silently turns false-green the day a validator starts reading a new doc; a positive list fails safe — any unlisted path, including a brand-new code input, forces the full suite. Seeded with docs/topics/ only. Adding an entry is a two-part proof (inert + a self-test case).
• scripts/check-docs-only.test.sh — the honesty proof, run unconditionally in both wrapped jobs before anything expensive.

In ci.yml, plugin-gate and miro-plugin each gain: fetch-depth: 0, an always-run detector self-test, a PR-only detect step (id: scope), an if: steps.scope.outputs.docs_only != 'true' guard on every install/test step, and an explicit "not applicable to a docs-only diff — reporting success" log step. On push the detect step doesn't run, the output is empty, and every real step runs — main always gets the full suite.

Job classification (only jobs that cannot be affected by a docs-only diff are scoped; when unsure, not scoped):

Lane	Scoped?	Rationale
plugin-gate	Yes	Heaviest lane. run-plugin-tests.sh is hermetic (tests build their own fixture repos); validate-plugins.sh reads only README.md, docs/PLUGIN-ARTIFACT-PROTOCOL.md, docs/CATALOG-TAXONOMY.md (all excluded from the allowlist) + plugins/** + toolchain files. A docs/topics/-only diff touches none of these.
miro-plugin	Yes	Every step is working-directory: plugins/miro; a docs-only diff provably cannot touch it.
hygiene	No	Markdownlint / typos / comment-hygiene do read the changed docs — this is the lane that should run on a docs PR.
skill-quality-gate	No	Already self-scopes to changed skills (empty set on a non-skill docs diff); eval-schema step is cheap.
zizmor	No	Advisory reusable workflow; scoping a reusable call partly belongs to ci-workflows.
hook-utils-sync, standards-contract-sync, cross-plugin-source-drift, silent-skip-gate, runner-policy	No (deferred)	Provably docs-inert, but off the critical path (fast bash tests, no heavy installs) — wrapping them adds surface for negligible latency gain. Trigger to revisit: if any becomes install-bearing.

Deferred with trigger: scoping miro-plugin to plugins/miro/** specifically (skipping it on any non-miro diff, not just docs-only) is a larger, separate optimization broader than #617's docs-only framing; trigger: a dedicated follow-up issue for per-lane path scoping.

Verification

In the worktree (ubuntu/Git Bash):

• bash scripts/check-docs-only.test.sh → PASS=16 FAIL=0. Cases pin: docs/topics/-only (incl. new nested files) → true; README.md, docs/PLUGIN-ARTIFACT-PROTOCOL.md, docs/CATALOG-TAXONOMY.md → false (the grep payoff — these are consumed by plugin-gate); any non-topics docs/**, any plugins/** incl. SKILL.md, scripts/, .github/, toolchain lockfiles, a sibling prefix (docs/topics-archive/), and mixed docs+code → false; unresolvable base ref → false exit 0; empty allowlist → false; $GITHUB_OUTPUT written.
• shellcheck --rcfile .shellcheckrc on both scripts → clean. shfmt -d → no diff. actionlint .github/workflows/ci.yml → clean.
• Provenance of the "inert" claim: git grep over plugins/**/*.test.sh, validate-plugin-contracts.mjs, generate-catalog.mjs, and the manifests confirmed generate-catalog.mjs --check consumes README.md and docs/CATALOG-TAXONOMY.md and validate-plugin-contracts.mjs requires docs/PLUGIN-ARTIFACT-PROTOCOL.md — which is exactly why those are excluded from the allowlist and the docs-only win is docs/topics/-scoped, not "all markdown".
• zizmor: base ref flows via env: BASE_REF (no ${{ }} interpolation inside run:), matching the existing hook-utils-sync/skill-quality-gate steps; persist-credentials: false retained; no new permissions.

Honest scope note: the win is narrow by construction — it covers docs/topics/-only PRs and deliberately does not cover README/philosophy edits, SKILL.md edits (code), or plugin-CHANGELOG edits (code). Narrow-but-sound is the point.

Related

• convention: false-green checks — surfaces report success while the capability is dead or findings invisible (liveness-assertion umbrella) #532 — false-green / liveness-assertion convention this honors (evaluated-and-not-applicable success, not a silent skip).
• feat(ci): add skill-quality static gate lane for changed skills (#530) #593 — the merged skill-quality-gate whose never-skip, self-test-first, event-gated job shape this mirrors.
• feat(ci): add portability-lint gate for ecosystem/forge-agnostic skills (#531) #609 — open PR also touching ci.yml (adds the portability-lint lane + one line to the ci-status needs list). Different file regions from this PR (new job block + needs line vs. the plugin-gate/miro-plugin step bodies); composes without conflict. Whichever merges second rebases.
• No plugins/<name>/ directory is touched, so no version bump / CHANGELOG entry (matching CI-only precedent fix(repo): add pull_request_template scaffolding ## Related contract #490/feat(ci): add skill-quality static gate lane for changed skills (#530) #593).

[claude]

Claude finished @kyle-sexton's task in 2m 34s —— View job

---

PR Review — perf(ci): short-circuit plugin-gate and miro-plugin on docs-only diffs

• Gather context and understand request
• Read changed files
• Review scripts/check-docs-only.sh
• Review scripts/check-docs-only.test.sh
• Review scripts/docs-only-paths.txt
• Review .github/workflows/ci.yml changes
• Post final review

---

Summary

The design is sound and the implementation is careful. The allowlist-not-blocklist safety property, fail-closed semantics, unconditional self-test, PR-only detect step, and env:-based injection safety all match the stated rationale and the patterns already established by #593/#609. Two findings below — one minor gap worth fixing before merge, one observation with no action needed.

---

Finding 1 — Minor gap: "missing allowlist file" path is not test-covered

scripts/check-docs-only.test.sh covers empty allowlist (lines 107–118) but not a non-existent allowlist file. The two code paths are different:

# path 1 — file missing (L42-46 of check-docs-only.sh)
if [[ ! -f "$ALLOWLIST" ]]; then  emit false; exit 0; fi

# path 2 — file exists but empty (L57-61)
if [[ ${#prefixes[@]} -eq 0 ]]; then  emit false; exit 0; fi

The missing-file path is two lines and trivial, but it is the one that fires when DOCS_ONLY_ALLOWLIST is accidentally set to a wrong path. Given the PR's own two-part proof contract, this deserves a test case alongside the empty-allowlist one:

repo="$(mk_repo)"
base="$(git -C "$repo" rev-parse HEAD)"
printf 'changed\n' >"$repo/docs/topics/example/PLAN.md"
git -C "$repo" add -A >/dev/null && git -C "$repo" commit -qm change >/dev/null
out="$(cd "$repo" && DOCS_ONLY_ALLOWLIST=no-such-file.txt bash scripts/check-docs-only.sh "$base" 2>/dev/null)"
if [[ "$out" == "docs_only=false" ]]; then
  ok "missing allowlist file -> false (fail-closed)"
else
  fail "missing allowlist: expected docs_only=false, got '$out'"
fi
rm -rf "$repo"

Fix this →

---

Finding 2 — Observation: glob metacharacters in allowlist entries (no action needed)

In check-docs-only.sh line 74:

if [[ "$path" == "$prefix"* ]]; then

"$prefix" is quoted, so glob metacharacters inside the prefix itself are treated literally — only the trailing bare * is a glob. An allowlist entry like docs/topics/ is safe. Worth knowing if entries with [, ?, or * are ever added; they would be silently misinterpreted as glob patterns in the unquoted suffix position. The current seed (docs/topics/) is clean, and the comment block in docs-only-paths.txt doesn't warn about this. A one-liner comment in the script near L74 would be sufficient if the allowlist ever grows to include paths with special characters — skipping for now is fine given the narrow scope.

---

Code quality notes (no issues)

• Fail-closed semantics correctly cover all edge cases: unresolvable base ref, missing allowlist, empty allowlist, empty diff, any unlisted path — all emit false and exit 0.
• env: BASE_REF: ${{ github.base_ref }} correctly avoids expression injection inside run: steps, consistent with hook-utils-sync/skill-quality-gate.
• fetch-depth: 0 is correctly added to both jobs — without it, git diff --name-only "origin/$BASE_REF" would fail to resolve the base commit, triggering fail-closed (safe but wasteful).
• Self-test runs unconditionally (no if: github.event_name == 'pull_request'), honoring the #532 liveness-assertion convention. On push, docs_only is never set to true, so the full suite always runs on main.
• miro-plugin not-applicable log step references docs-only-paths.txt by path — consistent with plugin-gate.
• 16/16 test cases cover: true path, nested-new-file true path, three false-negative regression guards (README, PLUGIN-ARTIFACT-PROTOCOL, CATALOG-TAXONOMY), seven conservative-false paths, and two fail-closed paths. The sibling-prefix case (docs/topics-archive/) is a welcome inclusion.

---

Verdict: Approve pending the missing-allowlist-file test case (Finding 1). Everything else is clean.