ci: path-scope heavy CI jobs so docs-only PRs skip them (merge-latency reduction)

[kyle-sexton]

Control-tower bottleneck finding (2026-07-20, operator-directed latency work). Docs-only pipeline PRs (a large share of current throughput: precedent codifications, SKILL.md doc fixes, CHANGELOG-only touches) run the full check suite. Add path filters so jobs that cannot be affected by a docs-only diff (plugin-gate deep checks, test suites, etc.) skip via path scoping WITHOUT violating the false-green/liveness convention (#532): required jobs must still report success honestly via the documented skip-safe pattern (self-test-first + explicit event gating per the #593/silent-skip precedent), never silent-skip.

Scope note: ci.yml job wiring is repo-side; if any change lands in a reusable workflow, that half belongs in melodic-software/ci-workflows.

Filed by the control-tower session.

[kyle-sexton]

This was generated by AI during triage.

T2 triage planning comment. Note: I verified against the live repo before planning — and the plan sketched here is already implemented and merged. This comment records that verification plus one empirically-measured residual gap that the human owner should route.

Status correction: the core ask is already delivered

#617 was implemented and merged by PR #622 ("perf(ci): short-circuit plugin-gate and miro-plugin on docs-only diffs"), commit 9932b27f, now the tip of main. The issue is already CLOSED. So this is a verification + gap-finding, not a fresh build plan.

What #622 did — verified correct and skip-safe

It gates the two heavy lanes (plugin-gate, miro-plugin) with a new detector scripts/check-docs-only.sh + a positive allowlist scripts/docs-only-paths.txt, and follows the #593/silent-skip precedent exactly:

• The job never skips. Only the inner install/test steps carry if: steps.scope.outputs.docs_only != 'true'; a docs_only run still executes the lane and prints an explicit "not applicable to a docs-only diff" success line. This is required here because a job-level skip would make the lane's needs.*.result = skipped, and the ci-status aggregate rejects any non-success result (and a path-filtered required workflow would leave its check Pending).
• Self-test first, unconditionally. scripts/check-docs-only.test.sh runs before the gated steps, so a broken detector cannot mask a regression behind a green short-circuit.
• Fail-closed toward running the full suite. Unresolvable base ref, missing/empty allowlist, or empty diff all emit docs_only=false.

The #532 false-green trap — correctly avoided (this is the load-bearing part)

The naive reading of "docs-only = **/*.md" would be a false green in this repo, because SKILL.md and README.md are first-class inputs to plugin-gate. Verified:

• plugins/planning/tests/standards-binding.test.sh and plugins/review/tests/standards-binding.test.sh assert on their own SKILL.md content (run by run-plugin-tests.sh).
• scripts/validate-plugin-contracts.mjs reads plugins/*/skills/**/*.md and enforces byte-identical docs/PLUGIN-ARTIFACT-PROTOCOL.md copies.
• scripts/generate-catalog.mjs --check reads the root README.md catalog block.

#622 sidesteps all of this by using an allowlist, not a blocklist: the only entry today is docs/topics/. SKILL.md, README.md, CHANGELOG, and every consumed doc are deliberately not listed, so any PR touching them forces docs_only=false and the full suite runs. Adding an entry requires a documented two-part inertness proof + a pinning self-test case. SKILL.md must never be added — it is a code input.

Residual gap: the stated merge-latency objective is NOT met (measured)

The issue's headline is "merge-latency reduction." The merged change delivers runner-minutes / concurrency savings but near-zero wall-clock latency reduction. Empirical evidence from the docs-only verification PR #623 (docs/topics/_verify-617/NOTES.md only, run 29720886079):

Lane	Full-run baseline	On the docs-only PR	Gated by #622?
plugin-gate	~88 s	5 s	yes
miro-plugin	~19 s	6 s	yes
hygiene	~92–105 s	105 s	no
wall clock → ci-status	~98 s	~111 s	—

plugin-gate and hygiene run in parallel, so ci-status still waits on hygiene. hygiene's runtime is dominated by its ShellCheck step (~53 s) — full-repo linting of all ~100+ shell files every run — which is docs-irrelevant but ungated. Net: a docs-only PR's merge latency is unchanged. Combined with the fact that the largest real "docs" category (SKILL.md fixes) correctly still runs the full suite, the merged optimization touches only a narrow slice (docs/topics/-confined PRs) and does not move merge latency at all.

Recommended follow-up (this is where the actual latency lives)

Route as a new focused issue; keep #617 closed as "core scoping delivered." Apply the same skip-safe discipline #622 used.

1. Repo-side — short-circuit hygiene's docs-irrelevant full-repo linters on docs-only diffs. The dominant cost is ShellCheck (~53 s); also actionlint, the four check-jsonschema steps, and exec-bit are docs-irrelevant. Reuse the existing check-docs-only.sh detector. Do not step-gate them inside the current shared-checkout hygiene job by weakening scripts/aggregate-hygiene-results.sh — it fails on any non-success outcome (incl. skipped) by design, and teaching it to pass on skipped would blur a deliberate gate-skip from a bug-skip (exactly the convention: false-green checks — surfaces report success while the capability is dead or findings invisible (liveness-assertion umbrella) #532 shape). The clean design is a dedicated step-gated lane (a job's success derives from its own steps, so gating the inner step is safe and the shared aggregator is untouched). The docs-linting checks — markdown, typos, editorconfig, gitleaks, eol-renormalize, comment-hygiene, machine-specific-paths — must stay on docs-only PRs.
2. Cross-repo (root cause, out of scope for this repo) — melodic-software/ci-workflows. The 53 s is non-incremental: the ShellCheck composite action lints the whole tree every run. The durable fix is incremental "lint changed files only." That is a ci-workflows composite-action change, not a repo-side one — flag as a cross-repo follow-up, do not attempt it from this repo's PR. Path-scoping is the legitimate caller-side mitigation until then.
3. Optional allowlist growth (repo-side, low value): add e.g. CHANGELOG.md to docs-only-paths.txt only via its two-part inertness proof + self-test case. Never SKILL.md. The plugins/miro/**-specific scoping of miro-plugin is already noted in-code as separately tracked.

Precedent honesty: #593 is event-gating; #622 correctly extended the same discipline (self-test-first, fail-closed, never a silent skip) to a path axis — it did not invent a different pattern. The follow-up should preserve that discipline.

Open decisions for a human (why this is needs-human)

1. Leave ci: path-scope heavy CI jobs so docs-only PRs skip them (merge-latency reduction) #617 closed as delivered vs. reopen/repurpose it for the latency objective.
2. Target metric: wall-clock merge latency (needs the hygiene/ShellCheck work above) vs. runner-minutes (already achieved) — different work, and the issue's stated goal points at the former.
3. Approval for the cross-repo incremental-ShellCheck change in ci-workflows.

Confidence: LOW / needs-human. The titled scope is implemented and correct, but the stated objective is empirically unmet and the real lever (hygiene ShellCheck, partly cross-repo) is an open design decision — not a mechanical next step.