feat: Add coverage-aware scanning and bounded Spectre analysis

[julio-rocketchat]

Summary

Upgrade the scan lifecycle to distinguish a clean result from missing coverage, and use that contract throughout Spectre, Dep Doctor, exception approvals, and notifications.

Base synchronization

#111–#115 are now merged into develop. This branch includes the latest develop via merge commit 2655aac, with all seven conflicted files resolved while preserving the integrated scanner contracts and merged fixes. The full 1,071-test suite, build, typecheck, lint, configuration validation, documentation build, and credential scan passed after resolution.

Included changes

1. Configuration and lifecycle: validate configuration before starting server/worker, inherit global scanner settings, propagate cancellation to subprocesses and requests, and coordinate terminal Check Run publication.
2. Canonical scan input: typed Git changes and unified diffs preserve renames, exact changed lines, and preparation gaps. PR metadata is explicitly untrusted and byte-bounded. Claude normally receives changed hunks plus context.
3. Truthful coverage: adapters return findings plus complete/incomplete/disabled status. Preserve valid partial findings, validate evidence before changed-line filtering, and expose incomplete coverage in Check Runs, comments, labels, and notifications.
4. Dep Doctor: expand npm/PyPI lockfile parsing, handle renamed/baseline lockfiles correctly, deduplicate registry checks, derive OSV severity, and use a separate lockfile size budget. Version-only dependency updates remain reportable in diff-only mode.
5. Bounded Spectre core: provider-neutral transports, whole-PR/related-file/hunk requests, lexical risk scoring, code-bearing file selection, request/input/output/call budgets, and high-risk overflow coverage failures.
6. Provider governance: in-process or Redis-backed concurrency/rate limits, circuit breaking, bounded admission, and associated Prometheus/Grafana observability.
7. Response validation: forced structured reporting calls, exact source grounding, bounded response/evidence repair, and diagnostics that omit raw provider errors and response contents.
8. Optional cache: signed PR/repository/build-scoped response envelopes, positive preservation, clean-result probation, TTLs, bounded storage, and revalidation on use. Disabled by default.
9. Optional AST routing: bounded JS/TS, Python, and Go structural analysis, isolated compiled workers, expanded execution signals, shadow/enabled modes, and structural cache versioning. Disabled by default.
10. Exceptions and notifications: evidence/rule-bound v2 finding IDs with legacy compatibility; one-shot current-head bulk approvals; precise rescan confirmations; per-notifier final-state fingerprints, event/severity policies, delivery retries, and independent cursors.
11. Evaluation: deterministic real-Git simulations, synthetic semantic/AST corpora, manual CLI evaluators, generic explicit-manifest PR replay, and comparison tooling. Generated reports are ignored. No live model evaluation was needed for this verification.
12. CI prerequisite: use npm ci instead of deleting the lockfile and resolving dependencies afresh. The old install step reproducibly crashes npm before compilation; this one-line prerequisite is also applied to fix: Validate clone destinations before attaching installation tokens #111–chore(docs): Upgrade Docusaurus and refresh documentation assets #115.

Why these belong together

The typed diff feeds selection, evidence grounding, dependency baselines, and cache identity. Adapter completion statuses determine final conclusions. Bulk approvals must waive findings without waiving missing coverage; notification deduplication must observe that final state. Splitting these interfaces across stacked PRs would introduce temporary compatibility behavior and leave their end-to-end contract untested.

Migration / behavior changes

• Node >=22.19 is required by the provider library.
• Custom adapters must return the structured result contract.
• Ordinary incomplete coverage normally yields neutral; high-risk Spectre file-cap overflow yields failure without fabricating findings. Neutral is not a guaranteed merge block.
• Invalid/unreadable configuration now prevents startup instead of silently using defaults.
• Notifications default to high/critical findings, internal errors, and effective approvals. Coverage notifications are opt-in.
• exception-approve all freezes findings from the approval rescan, not a persisted snapshot of the previous scan; retries cannot expand the frozen set.
• Cache and AST analysis remain opt-in. Cache signatures provide integrity, not encryption; Redis entries can contain source evidence.
• A major changeset documents the changed contracts/defaults.

Verification

• Node 22: npm run build, npm run typecheck, npm run lint, npm run validate-config all passed.
• 1,071 tests passed across 50 files, including cancellation/publication races, malicious-output rejection, real temporary Git histories, and AST adversarial/stress cases.
• Deterministic simulator: 9/9 scenarios passed. These are scripted transport results, not a claim about live-model detection accuracy.
• Dedicated real Redis integration passed: cache CAS, scope isolation, negative probation, positive preservation, tamper rejection, eviction and expiry; cross-instance governor contention and circuit recovery; bulk approval head binding and frozen retries.
• Real Redis + loopback HTTP notification tests passed: delivery, transient retry, deduplication, stale ordering, and quiet-state filtering.
• Compiled AST worker/WASM loading and cancellation passed, including the non-root Linux ARM64 production image with networking disabled.
• A disposable cumulative integration worktree merged fix: Validate clone destinations before attaching installation tokens #111–chore(docs): Upgrade Docusaurus and refresh documentation assets #115 with this branch without conflicts. Fresh locked installs, all checks/tests, the production documentation build, and the complete Alpine image build passed.
• Production image smoke tests passed for health, configuration validation, and rejection of invalid webhook signatures.

Security review

• Reviewed credential-bearing URLs, Git/path boundaries, parser input, provider response grounding, cancellation, approval authorization/replay scope, Redis scripts, logging, and dependency provenance.
• Fixed repository-controlled temporary-path redirection by allocating unpredictable worker-owned projection/baseline directories.
• Fixed filtered notification delivery during Redis lock outages; rejected unverified stale exceptions; removed raw provider/evaluator error details from logs/reports.
• Semgrep TypeScript scan of production source/scripts: no findings or scan errors.
• Gitleaks scan of the complete new commit history: no leaks found.
• Reviewed new provider, telemetry, YAML/TOML, and Tree-sitter packages and registry metadata. Removed unused legacy agent dependencies; retained the public BullMQ version floor.
• Root npm audit affected-package count decreased from 22 to 15, with no newly named affected package. Existing advisories remain and are not claimed fixed by this PR.
• Public repository configuration, rules, deployment workflows, and Nginx configuration are unchanged. The test workflow has only the approved one-line locked-install fix. Evaluators use generic configuration defaults and explicit replay manifests.

Related overlapping contributor work: #77, #78, #79, #81. Their branches are unchanged; maintainers can reconcile overlapping fixes during review.