Design wfctl repo audit quality gate #488

Goal

Design and implement a dogfooded local/CI quality gate for wfctl that catches review-style issues before PR push/merge.

Intent

This should align with wfctl's purpose: reduce project lifecycle friction across Workflow projects and downstream apps. It should not become a large hard-coded grab bag inside the binary. Prefer a small core command with plugin/extensible checks where project-specific or ecosystem-specific logic belongs.

Principles

• Support non-Go projects holistically, not just Go repos.
• Use Workflow/wfctl to validate Workflow/wfctl where practical.
• Keep core wfctl focused on orchestration, discovery, config, reporting, and common safety checks.
• Use the plugin system for language/framework/provider-specific checks when that keeps the core binary smaller and cleaner.
• Prefer stable machine-readable output so CI, MCP, and agents can consume results.
• Make local and CI behavior match as closely as possible.

Candidate scope

• wfctl audit repo or wfctl audit pr command for repo-level quality gates.
• Built-in checks for portable docs/frontmatter, generated index drift, stable JSON output, unresolved PR review threads, unsafe path patterns, and command output routing.
• Plugin-provided check packs for Go, GitHub Actions, Markdown, Node, Gradle/JVM, frontend, etc.
• Optional integration with Semgrep/actionlint/golangci-lint when installed or declared by project config.
• Project config for enabled checks, severity, ignore rules, and required tools.

Questions to resolve in design

• What belongs in core vs plugin-provided checks?
• Should check packs be Workflow plugins, wfctl plugins, or manifest-driven external tools?
• How does this work for non-Go projects without pulling large language toolchains into wfctl itself?
• How do agents/MCP consume audit results and link findings back to PR comments?
• How do we prevent this from duplicating CI while still catching issues before push?

Motivation

Workflow PR #487 surfaced repeated deterministic issues through Copilot review that could have been caught locally: non-portable docs paths, malformed frontmatter handling, unstable JSON field names, flag output routing, and brittle tests. These should become local dogfood checks rather than relying on external PR review.