Metadata-Version: 2.4
Name: nucleus-scan
Version: 0.1.3
Summary: AI Hygiene Report — scan a project for plan rot, dep CVEs, and ungrounded reasoning in your AI sessions.
Author: Nucleus
License: MIT
Keywords: ai,claude-code,cursor,audit,hygiene,lint
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: cve
Requires-Dist: pip-audit>=2.6; extra == "cve"
Dynamic: license-file

# nucleus-scan

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

## Install / Run

```bash
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

```yaml
# .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.
