kenlck Audit Software Fleet
Audit the configured repositories individually and as one interacting system. Keep the run read-only and evidence-led; label absence of evidence as incomplete coverage rather than a pass.
1. Frame the run
Resolve fleet.yaml, fleet-policy.yaml, and an optional system-map.yaml. Default to safe mode. Treat deep mode as authorized only when the user explicitly requests it, policy enables it, and each targeted repository opts in. Authorization is not execution: suite 0.1.0 has no executable deep adapter, records executed_mode: safe, and emits an explicit deep-execution coverage gap. Treat advisory refresh as authorized only when the user explicitly requests it and policy enables network refresh.
Read references/configuration.md when creating or diagnosing configuration. Read references/safety-model.md before any deep execution, network refresh, or scanner invocation.
Complete when: every repository has a stable name and source, requested, authorized, and executed modes are explicit, every deep target passes all three authorization gates, and any refresh passes its user-and-policy gates.
2. Validate and collect once
Resolve scripts/fleet_audit.py relative to this file and keep its absolute path as runtime. Invoke that path from any working directory (use the platform-equivalent quoting):
python "$runtime" validate --fleet <fleet.yaml> --policy <fleet-policy.yaml> [--system-map <system-map.yaml>]
python "$runtime" collect --fleet <fleet.yaml> --policy <fleet-policy.yaml> [--system-map <system-map.yaml>] --mode <safe|deep> [--authorize-deep] [--refresh-advisories] [--gate <profile>] [--output <directory>] [--cache <directory>] [--max-workers <n>]
Use the run directory printed by collect. The runtime prepares isolated repositories, records exact commits, builds the inventory and interaction graph, and runs only allowed deterministic adapters. Keep one inventory and graph for the entire run.
Read references/scanner-adapters.md when configuring tools or interpreting adapter failures.
Complete when: the run directory contains validated inventory.json, system-map.json, evidence/index.json, and lenses/requests/<lens>/batch-*.json assignment files for the available selected scope; every unavailable repository is recorded in inventory.json. Final coverage.json is created only during rendering.
3. Dispatch bounded lens reviews
Run the required lens skills named by the policy. Give each worker the run directory, a bounded repository batch, and the relevant inventory, graph, and evidence—not the entire fleet checkout. Use adaptive concurrency up to the policy limit (four by default); fall back to sequential review when parallel workers are unavailable.
Each lens is directly invokable and owns its review guidance:
$review-tech-lifecycle$review-application-security$review-test-quality$review-software-reliability$review-codebase-design$review-delivery-supply-chain$review-operability$review-performance-efficiency$review-engineering-governance$review-system-integration
Require every worker to emit the shared lens-result contract in references/finding-contract.md. Ingest each result:
Workers follow references/standalone-lens.md for preparation, preflight, validation, and artifact handoff.
python "$runtime" ingest --run-dir <run-dir> --result <lens-result.json>
Continue past an optional lens failure. Ingest a valid partial result when the worker can account for attempted sources and exact gaps; otherwise leave it un-ingested so the runtime emits a generic incomplete-coverage placeholder. Preserve a required-lens failure for gate evaluation; never improvise the missing review or a failure reason the worker did not return.
Complete when: every policy-selected lens has either a validated result or an explicit coverage record for every assigned repository and system.
4. Correlate, render, and report
Run:
python "$runtime" render --run-dir <run-dir>
The runtime normalizes, redacts, correlates, and deduplicates results before writing the self-contained offline report. Read references/html-report-format.md only when changing or checking the renderer. Normal advisory findings leave the command successful; only an explicit gate profile can return a policy-gate failure.
Report the run directory, exact coverage, highest-priority evidence-backed findings, strengths, unknowns, and gate result. Keep recommendations advisory. The audit never changes source repositories, tickets, pull requests, or external systems.
Complete when: all JSON artifacts validate against the pinned suite contract, index.html opens offline, coverage gaps are prominent, and the reported exit status matches references/finding-contract.md.
Standalone deterministic run
For CI inventory, static policy checks, pre-existing lens results, and report rendering, use:
python "$runtime" run --fleet <fleet.yaml> --policy <fleet-policy.yaml> [--system-map <system-map.yaml>] [--mode <safe|deep>] [--authorize-deep] [--refresh-advisories] [--gate <profile>] [--output <directory>] [--cache <directory>]
run does not replace contextual lens review. Its coverage output names every lens that still requires a host agent.