TEST(875): single-idea enhancement validation

[don-petry]

This is a throwaway test idea to validate the folded single-idea enhancement path of the feature-ideation workflow. Idea: add a lightweight CLI flag that lets contributors preview compliance findings locally before pushing, reducing CI churn.

[github-actions[bot]]

Enhancement: Local Compliance Preview — Prior Art, Options & Pilot Path

Sharpened problem & goal
The idea — letting contributors preview compliance findings locally before pushing — targets a real feedback-loop gap: compliance checks run in CI (via scripts/compliance-audit.sh), and failures force a push → wait → read-failure → fix → re-push cycle. The sharper question is: which subset of compliance checks are (a) locally reproducible and (b) responsible for the most CI churn? A blanket "run everything locally" approach risks environment drift; a targeted subset delivers 80% of the value at 20% of the maintenance cost.

Context & existing infrastructure

• scripts/compliance-audit.sh already defines the check catalog: required workflows, required labels, required repo settings, CodeQL default-setup verification, and check-suite auto-trigger audits.
• shellcheck scripts/*.sh is documented in CLAUDE.md as a local lint command — contributors already have one local check.
• The compliance audit uses gh api calls that require a token with org scope — most of its checks cannot run locally without credentials (repo settings, label existence, workflow file presence on remote).
• The checks that can run locally are static analysis: shellcheck, actionlint (workflow YAML correctness), and file-existence checks (REQUIRED_WORKFLOWS array).

Prior art / competitive signal

Tool	Local mode	Relevance	Adoption
pre-commit (pre-commit.com)	Native; runs at git commit	Hook-based; 13k+ stars; CPython, FastAPI use it	Very high
prek (Rust rewrite of pre-commit)	Native CLI	Emerging (2025–26); adopted by CPython, Airflow, Ruff	Growing
nektos/act	Docker-based Actions replay	57k+ stars; full workflow replay but requires Docker, imperfect parity	High
Trunk Check (trunk.io)	Hermetic CLI with hold-the-line	Lints only changed files vs. upstream; free for ≤5 committers	Medium
MegaLinter	Docker image, 48 languages	Unified local/CI experience; heavy cold-start	Medium
actionlint	Single binary, ~6ms	Workflow YAML correctness + auto-pipes run: blocks through shellcheck	High
ci-doctor	Single binary	Catches cost/reliability rules (missing-concurrency, cron-storm) that actionlint misses	Emerging

Market trend: "shift left" is evolving into "shift smart" — surfacing only relevant, high-signal findings locally rather than dumping raw scan output. AI-generated code (41% of new code per JetBrains 2025 survey) raises the pre-commit hook importance further, as non-human authors skip mental compliance checklists.

Options table

Option	Description	Pros	Cons
A. Thin wrapper script	scripts/compliance-check-local.sh runs shellcheck + actionlint + file-existence checks	Zero new deps; matches repo convention; can be CI-sourced too	Must manually sync with CI; covers only static checks
B. pre-commit config	.pre-commit-config.yaml with shellcheck + actionlint hooks	Auto-runs on commit; pre-commit run --all-files for on-demand	Requires Python; hook config is separate from CI config
C. Make/Task target	make lint or task lint calling shellcheck + actionlint	Language-agnostic; familiar to all	Same sync risk as A; adds a task runner dependency

Recommendation: Option A — a thin wrapper script — fits this repo's shell-first convention and avoids new toolchain dependencies. The script can be called from CI too (single source of truth), eliminating the config-drift risk.

Risks / unknowns

Risk	Severity	Mitigation
Local/CI tool version drift	Medium	Pin versions in the script; use mise/asdf for version management
Config drift (script diverges from CI)	High	CI workflow sources the same script — one definition, two execution sites
False confidence (local pass ≠ CI pass)	Medium	Document what the local check covers vs. what requires remote API scope
Developer friction from slow hooks	Medium	Keep under 10s; scope to the highest-signal checks only

Phased pilot path

1. Measure: Query recent CI runs to identify which compliance failures occur most frequently — target the top 3.
2. Script: Create scripts/compliance-check-local.sh running shellcheck + actionlint (the two statically-reproducible checks). Have CI call the same script.
3. Document: Add a make lint-local target and a one-liner to CONTRIBUTING.md.
4. Measure again: After 4 weeks, compare compliance-related CI failure rates (before vs. after).

Success metrics

• ≥50% reduction in compliance-related CI re-pushes within 4 weeks of adoption
• Local check completes in <10s on a developer laptop
• Zero config-drift incidents (CI and local use the same script)

[github-actions[bot]]

Sharpened problem & goal

Add a single local entry-point command that mirrors what lint.yml gates on CI — shellcheck, bats, and settings/ruleset drift — so contributors can surface failures before pushing instead of after. The ambiguity worth resolving: does "compliance findings" mean only shell/test lint, or does it also include settings drift (check-suite auto-trigger state, ruleset divergence from .github/rulesets/)?

Context

The constituent pieces already exist and most already support a read-only or dry-run mode:

• shellcheck scripts/*.sh — documented local lint command (CLAUDE.md § Commands).
• bash scripts/run-bats.sh tests/ — runs the full bats suite locally.
• scripts/apply-repo-settings.sh with DEV_LEAD_DRY_RUN=true — prints what it would change without making API calls.
• scripts/apply-rulesets.sh with DRY_RUN=true — same pattern for rulesets.

The missing piece is a thin scripts/preflight-check.sh wrapper that composes these four checks, prints a per-check pass/fail summary, and exits with a unified code. This matches how dev-lead-preflight.sh works for secrets validation — the same pattern applied to compliance checks.

Impact / Effort

Impact	MEDIUM — reduces CI round-trips and speeds up contributor workflow; especially valuable as the bats suite and ruleset surface grow
Effort	S — all constituent checks already exist and support dry-run / read-only modes; the wrapper is ~50 lines of POSIX shell

Suggested acceptance criteria

• bash scripts/preflight-check.sh (no args) runs shellcheck over scripts/, the full bats suite, and the dry-run path of apply-repo-settings.sh + apply-rulesets.sh against the current repo.
• The script prints a per-check pass/fail summary and exits 0 only if all checks pass (mirrors CI exit semantics).
• scripts/preflight-check.sh passes shellcheck itself and has a corresponding test in tests/test_preflight_check.bats (added to the bats list in lint.yml per AGENTS.md exception pattern).
• Documented in CLAUDE.md under Commands alongside shellcheck scripts/*.sh.
• Clarify scope: should the preflight also validate action-pin SHAs for third-party workflow actions (flagging un-pinned steps), or is that out of scope for a local tool?