feat: detector precision, monorepo discovery, CI gate + honest docs restructure

[decksoftware]

Summary

Engine/CLI hardening and a documentation restructure so the project presents itself as what it is: an orchestration, corroboration, and evidence layer for local security review — complementing Semgrep and the other scanners, never replacing them.

Engine & CLI

• XML_XXE precision fix: the old .*?(?!...) lookahead was always satisfiable, so ANY mention of an XML parser (including the entity-free browser DOMParser) produced a CRITICAL false positive — empirically proven, then rewritten to fire only on explicitly insecure entity configuration (noent: true, resolve_entities=True, LIBXML_NOENT, DtdProcessing.Parse, ...). Audited all 9 lookahead patterns; the other 8 are positionally correct. Precision corpus extended with safe/insecure XXE pairs.
• Monorepo discovery: config/dependency/BaaS patterns are now recursive (**/), so apps/*/.env, services/*/Dockerfile, nested package.json/firestore.rules are scanned; one parallel glob walk per category (was ~87 sequential walks); /-normalized paths; frameworks detected from ALL workspace manifests.
• Strict CLI: node:util parseArgs — a mistyped flag (--basline) now aborts instead of silently running without the baseline. New --version and --fail-on <severity> (exit 1 when findings at/above the level remain → CI gate to pair with the SARIF output).
• Tool control: --tool-timeout <s> (timeouts reported as timeouts, with the knob named, instead of generic "unavailable") and --semgrep-config <ref> for local/air-gapped rules (adds --metrics=off).
• Consolidation: single sanitizeAgentName module (was 3 drifting copies), shared extension/language maps (fixes *.pyw never getting Python rules), single content split per file in the detector.

CI

• New dogfood self-scan job: every PR runs CSReview against this repository with Semgrep installed and fails on remaining HIGH/CRITICAL findings — exercising the new gate end to end.

Documentation honesty

• SKILL.md: 1948 → ~250 lines, engine-first ("run the CLI; never handcraft reports"), consolidated core rules, and an explicit no-fabricated-metrics rule: the old report templates instructed agents to fill in ASVS Coverage %, SLSA Level, and per-article compliance PASS/FAIL that the engine does not compute. DAST-CONFIRMED is documented as a reserved label the built-in probe never emits; dotnet build is no longer listed as a security scanner.
• Checklists/compliance/tooling/subagent/DAST/report reference moved to csreview/reference/*.md (shipped in the package, loaded on demand — agents stop paying ~2k lines of context per invocation).
• README rebuilt as an honest landing (pipeline, explicit "Honest limits" section, updated CLI) keeping the verbatim SKILL.md mirror; the doc-honesty contract tests in analysis.test.js now assert across README + SKILL.md + reference/*.

Test plan

• 201/201 tests (18 new: XXE precision, monorepo scanner, CLI args, tool args/timeouts, agent-name, languages) — all 15+ doc-honesty contracts green
• npm run lint + npm run typecheck clean
• Dogfood self-scan: score 95/100, --fail-on high → exit 0; --fail-on low → exit 1 (gate verified in both directions)
• Self-scan job runs in this PR's own CI

🤖 Generated with Claude Code