ux: add consolidated Tier 1 scanner preflight and guided bootstrap

[chrisknvidia]

Context

OpenClaw onboarding feedback found the Tier 1 scanner installation experience difficult to understand. Bandit and pip-audit are available through the security extra, while Semgrep, Gitleaks, and SkillSpector are installed separately.

SkillEvaluator already detects each missing scanner during validation, emits an installation hint, marks the scan INCOMPLETE, and keeps the default external profile non-green. The remaining gap is that this information appears piecemeal during validation rather than as one upfront readiness check.

SkillSpector and Semgrep are currently kept in isolated tool environments so their dependency stacks do not constrain the SkillEvaluator distribution. Directly adding SkillSpector as a package dependency therefore needs an explicit compatibility and distribution decision rather than being assumed.

Goal

Provide a consolidated Tier 1 scanner preflight and guided, consent-based bootstrap experience without silently installing system tools.

Requirements

• Report availability, resolved executable path, version, and configuration errors for Bandit, Semgrep, Gitleaks, and SkillSpector in one place.
• Distinguish bundled Python scanners from independently installed executables.
• Show exact platform-appropriate installation commands for missing tools.
• Support a non-interactive CI mode that fails clearly when required scanners are unavailable.
• Never install or modify system tools without explicit user consent.
• Preserve executable override support and isolated-tool-environment compatibility.
• Evaluate and document whether SkillSpector can be bundled safely or should remain an independently bootstrapped tool.

Acceptance criteria

• One preflight command reports the complete Tier 1 scanner readiness state.
• Missing tools receive actionable macOS, Linux, and supported Python-tool installation guidance.
• CI can require a complete scanner set without interactive prompts.
• Any guided installation requires explicit confirmation and reports exactly what will change.
• Existing INCOMPLETE and non-green semantics remain intact.
• A documented decision records whether SkillSpector is bundled or intentionally remains isolated.
• Tests cover missing, malformed override, incompatible version, and fully ready states.

[rookepoole]

I’d like to take this. I traced the current scanner resolution and failure semantics and propose the following contract before implementation.

Command surface

• Add an advertised skillevaluator scanner-preflight command, with skillevaluator tier1 scanner-preflight as the existing expert-alias pattern.
• Require no target path. The default operation is read-only and probes Bandit, Semgrep, Gitleaks, and SkillSpector together.
• Report one bounded row per scanner: readiness state, distribution class (bundled-security-extra, external-tool, or explicit override), resolved executable path, parsed version, configuration/probe error, and platform-specific remediation.
• Use explicit states rather than a boolean: READY, MISSING, MISCONFIGURED, INCOMPATIBLE, and PROBE_FAILED.
• Exit 0 only when every required scanner is ready; exit 1 for any missing/misconfigured/incompatible/probe-failed scanner. Preserve Click’s exit 2 for command-usage errors.
• Add --json as the non-interactive CI contract. It never prompts and emits the same states/exit code as the human table.

This should be a Tier 1 command rather than an extension of doctor: the current doctor/health-check surface is specifically live-evaluation/provider/agent/sandbox readiness, while scanner readiness has no target or Tier 3 dependency.

Resolution and version probes

• Reuse the current interpreter-sibling/PATH/absolute-override resolution order, including fail-closed malformed override handling.
• Probe each resolved executable with an argv-only bounded subprocess (--version, with a per-tool parser); do not invoke a shell.
• Enforce the existing Bandit floor (>=1.9.4) and Gitleaks v8 compatibility. For Semgrep and SkillSpector, I suggest reporting parseable versions without inventing a minimum until maintainers identify the oldest supported CLI/JSON contract. The incompatible-version regression can cover old Bandit and non-v8 Gitleaks.

Consent-gated bootstrap

• Add --bootstrap only for an interactive TTY. It first prints the exact commands and affected tools, then asks for confirmation before each command.
• Refuse --bootstrap with --json or in a non-interactive session. Declining leaves the system unchanged.
• Execute only user-scoped isolated Python-tool installs (Semgrep and SkillSpector) as argv lists after confirmation. Do not use sudo, silently reinstall/upgrade the running SkillEvaluator environment, or invoke a shell.
• Treat Bandit/security-extra repair and Gitleaks package/binary installation as guided manual steps: print exact macOS/Linux commands and re-run instructions, but do not modify the current environment or system package directories from inside SkillEvaluator.

If the intended scope is for the CLI to execute Homebrew/Go/Gitleaks installation too, I’d prefer an explicit maintainer decision because that materially expands the mutation and rollback surface.

SkillSpector distribution decision

I recommend documenting that SkillSpector remains independently bootstrapped rather than adding it to skillevaluator[security]. Current SkillSpector 2.9.6 supports Python 3.12–3.14, but its package brings the LLM/LangGraph/provider stack into a deterministic Tier 1 install and explicitly documents isolated uv tool install usage. Keeping the executable/process boundary preserves the existing dependency-isolation rationale and provider-environment bridge.

Tests/docs

I would cover fully ready, each missing scanner, malformed overrides, version parse/probe failures, incompatible Bandit/Gitleaks, JSON/TTY behavior, declined bootstrap, confirmed argv execution, and no-shell/no-sudo guarantees. Documentation would update installation, Tier 1, CI, CLI reference, environment variables, and the Unreleased changelog while preserving existing INCOMPLETE/non-green validation semantics.

Two decisions before I start the implementation:

1. Is scanner-preflight the preferred advertised name, or should this be tier1 preflight only?
2. Is the limited bootstrap above acceptable, or should this issue include confirmation-gated execution of system/package-manager commands as well?