nucleus-scan 0.1.3

AI Hygiene Report — scan a project for plan rot, dep CVEs, and ungrounded reasoning in your AI sessions.

nucleus-scan

One-screen AI Hygiene Report for your repo. Surfaces plan rot, dep CVEs, and ungrounded reasoning in under 30 seconds.

Install / Run

uvx nucleus-scan                           # scan cwd
uvx nucleus-scan /path/to/repo
uvx nucleus-scan --json                    # machine-readable
uvx nucleus-scan --fail-under 70           # CI gate
uvx --with pip-audit nucleus-scan          # enable the CVE engine

The CVE engine shells out to pip-audit. If you don't pass it via --with, the engine reports N/A and its weight redistributes across the other two — the rest of the report is unaffected. You can also install the bundled extra: pip install 'nucleus-scan[cve]'.

What it checks

Engine	Weight	Signal
plan_rot	40%	plans under plans/, .claude/plans/ missing ## Verification or with drifted referenced files
cve	40%	pip-audit -r requirements.txt — project-scoped, not global
intel	20%	ungrounded corrections mined from ~/.claude/projects/<repo>/*.jsonl

An engine that doesn't apply (no requirements.txt, no plans dir, no Claude Code sessions) is reported as N/A and its weight redistributes across the remaining engines. If all three are N/A, the score is "Insufficient signal" rather than a misleading 100/100.

Exit codes

• 0 — success (or score ≥ --fail-under)
• 1 — score below --fail-under N
• 2 — guard violation (refused to scan $HOME or /, or bad path)

CI integration

pre-commit

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/eidetic-works/nucleus-scan
    rev: v0.1.2
    hooks:
      - id: nucleus-scan

nucleus-scan must be on PATH (install via pipx install nucleus-scan or uv tool install nucleus-scan). The hook runs nucleus-scan --fail-under 70 against the repo; tune by editing entry in your local config.

GitHub Actions

Copy nucleus-scan/.github/workflows/nucleus-scan.yml into your repo at .github/workflows/nucleus-scan.yml. It runs uvx --with pip-audit nucleus-scan --fail-under 70 on every PR and push to main. Override the threshold via repo variable NUCLEUS_SCAN_FAIL_UNDER.

Status

v0.1.2 — adds pre-commit + GitHub Actions templates. Requires pip-audit on PATH (or uvx --with pip-audit) for the CVE engine.