runtime planning: preflight declarative component prerequisites

[bomly-guy]

Summary

Consume the optional SDK prerequisite metadata from bomly-dev/bomly-sdk#29 to detect impossible component plans early and explain why a selected component cannot run.

Context

Bomly has a finite command-scoped pipeline and registry selection/fallback logic. Components already implement Ready and Applicable, but those imperative checks happen only after selection and cannot power static documentation or early configuration diagnostics.

The SDK issue deliberately models requirements as data/host capabilities, not named provider dependencies. The CLI should evaluate those requirements against the known request and current pipeline stage; it should not build a general dependency-injection scheduler.

Examples include a component requiring vulnerability records, a source-tree target, a dependency graph, or host support for package-update deltas.

Dependency

Blocked on the released SDK descriptor contract in bomly-dev/bomly-sdk#29. Do not commit a replace; pin the SDK tag after it is published.

Required behavior

• Build a small planner/evaluator over the fixed detector -> matcher -> analyzer -> auditor pipeline.
• Evaluate declared data requirements against actual request/target state and host capabilities.
• Produce a structured, actionable reason containing component name, unsatisfied requirement, and the stage/data that would satisfy it.
• Define in the ADR whether an explicitly selected component fails the command and whether a default/implicitly selected component is skipped with a diagnostic.
• Treat missing metadata as legacy/unspecified and continue through existing Ready/Applicable behavior.
• Treat unknown versioned requirements conservatively; never assume they are satisfied.
• Continue to call Ready and Applicable for plans that pass static preflight.

Acceptance criteria

• An ADR under dev-docs/adr/ fixes explicit-vs-default failure behavior, diagnostic shape, unknown-token handling, and stage capability definitions.
• All four component kinds can be preflighted without special-casing provider names.
• Unsatisfied requirements are reported before the component action method runs.
• Absent prerequisites preserve behavior for every existing v1 plugin.
• Unknown requirements produce a deterministic unsupported/unsatisfied result rather than being silently ignored.
• Requirements are visible in relevant plugin inspection or generated documentation output.
• Tests cover satisfied and unsatisfied requirements, explicit and implicit selection, SBOM-only vs source-tree targets, empty registries, and host capability negotiation.
• Hypothetical named/cyclic provider requirements are rejected or remain unrepresentable; no topological service scheduler is introduced.
• Ready, Applicable, registry filters, fallback chains, and fixed pipeline ordering remain authoritative after preflight.
• The CLI pins a released SDK version and generated docs/schemas are updated.

Compatibility

This is consumption of optional additive v1 metadata. Old plugins omit it and must continue to work. A new plugin declaring a requirement may be rejected by an older host only insofar as the older host ignores unknown descriptor fields; it must not break decoding.

Out of scope

• Plugin-to-plugin service lookup.
• Reactive activation, daemon reconciliation, or hot module replacement.
• Reordering the fixed pipeline to satisfy arbitrary dependencies.
• Making prerequisite declarations mandatory.

Verification

Run:

make test
make build-lite
make generate