Audit profiles

Every project has four audit profiles. Each one has its own methodology, campaigns and model enablement. Findings, dedupe and triage stay project-wide.

Hygiene and Pipeline need thespider-agent 0.7.0 or later. See Agent versions.

Hygiene

Hygiene is in beta.

Every hygiene finding carries two extra report fields:

• Usage evidence (usage_evidence): how non-use or staleness was established. That means the searches the model ran, what they found, and the dynamic and external uses it ruled out.
• Removal risk (removal_risk): what could break, and who outside the checkout could depend on it.

recommendation is the removal plan: everything that goes with the item (code, tests, config, docs, dependencies). impact is what keeping it costs.

An absence of local references is not enough. Public APIs, exported packages, plugin entry points and anything configured from outside the repository are never treated as unused just because the repository does not call them. A passed date alone does not make a TODO stale.

The Hygiene methodology instructs models never to rate a finding critical; its ceiling is high. This is guidance to the model, not a server rule: a critical hygiene finding that does come back is stored as reported. Reclassify it in triage.

Deterministic tools such as knip, depcheck, cargo-udeps and Renovate remain better at exact dependency detection. Hygiene focuses on the judgment calls those tools cannot make.

Kept on purpose

Kept on purpose is how Hygiene shows wont_fix: the item is real cruft, but not worth removing. It stays open, drops out of the actionable views, and does not block the PR gate. It is not the same as Not cruft (false_positive), which says the finding is wrong.

Pipeline

Pipeline is in beta.

Pipeline is static only. It reads your CI configuration, build files and test harness, and the scripts they invoke. It reads no timing data and never runs builds, tests or benchmarks to measure them. TheSpider is not a CI timing dashboard.

• Findings cite the CI, build or test file lines that cause the cost.
• impact states the saving structurally, for example "skips 4 of 7 jobs on docs-only PRs" or "builds the image once per pipeline instead of three times". It never states minutes.
• Cost driver (cost_driver): where the time or compute goes, what triggers it, and whether it sits on the merge or critical path.
• Verification plan (verification_plan): which job durations or pipeline counts to compare in your own CI before and after the change.
• recommendation is the change, plus what keeps correctness and security coverage.

Severity follows two axes. Frequency, highest first: every pull request, every commit to the default branch, nightly or tag pipelines. Kind, highest first: latency on the merge or critical path, a full redundant job of compute, part of a job. critical is reserved for exceptional, clearly evidenced blockage of the merge path on every pull request.

Limitation: inline test modules, for example Rust #[cfg(test)] blocks inside source files, are outside the starter test-harness pass. The model still follows the CI test commands into them.

Optional timing ingestion (JUnit or CI durations) is a possible follow-up, not part of this profile.

Hardening note

Hardening note is the one label for evidence_basis = speculative in every profile. What it means depends on the profile:

Cross-profile identity

Findings, dedupe and triage are project-wide, so one finding can collect reports from several profiles.

• The merge guard reads each finding's categories through the starter category codes of the four profiles. When the two sets map to different profiles and either side maps to Hygiene or Pipeline, the pair never merges automatically and no AI adjudication is spent on it. A Hygiene "unused dependency" on package.json therefore cannot absorb a Security "supply chain" finding on the same file.
• The guard is not a guarantee. Findings with empty or custom categories are not covered and can still merge across profiles, and a custom category that reuses a Hygiene or Pipeline starter code counts as that profile. A finding whose categories span Hygiene and another profile can merge with either.
• A merge can erase a Kept on purpose decision: the surviving finding keeps its own status.

PR gate

The PR gate runs exactly one profile: the project default.

• Switching the default away from Security removes security gating on every PR. TheSpider does not recommend it.
• A Hygiene default fails PRs on cruft.
• A Pipeline default fails PRs on pipeline findings.

Run Hygiene and Pipeline as scheduled or manual campaigns instead.

Because of this, choosing Hygiene or Pipeline as a new project's first audit (the dashboard's New project form, thespider-agent setup, or the MCP thespider_init tool) keeps Security as the project default. The first audit runs with an explicit --profile hygiene or --profile pipeline, and the commands TheSpider prints include it. To gate pull requests on another profile, an admin changes Default profile in the project's Settings, which warns before a non-Security default is saved.

Cost

A campaign plans 6 slices per enabled model (2 passes × 3 buckets), the same as Security and Bugs. Model enablement is per profile (Settings → Models). Projects that existed before these profiles were added got Hygiene and Pipeline with their default profile's model enablement.

An incremental Pipeline campaign over application-only changes plans zero slices: no CI, build or test file changed.

Agent versions

Hygiene and Pipeline need thespider-agent 0.7.0 or later.

• thespider-agent 0.6.0 and older fail on a project whose default profile is Hygiene or Pipeline unless you pass --profile security or --profile bugs.
• They also fail to load a committed .thespider/config.toml with profile = "hygiene" or profile = "pipeline".

setup therefore writes that line commented out:

# profile = "hygiene"   # requires thespider-agent >= 0.7.0

Pass --profile hygiene or --profile pipeline to run, daemon and findings instead, until every machine on the project runs 0.7.0 or later.