@softspark/ai-toolkit 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -7,6 +7,35 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v1.5.0 — HIPAA Scanner: Deterministic Script, CI Integration, Self-Exclusion (2026-04-10)
+
+### Added
+- **`scripts/hipaa_scan.py`** — deterministic Python scanner (stdlib-only) for `/hipaa-validate`. Replaces LLM-driven regex execution with a reproducible script. 8 check categories, context gate, `.hipaaignore` support, `.hipaa-config` BAA vendor list, deduplication, structured output.
+- **`--output json` flag** for `/hipaa-validate` — structured JSON output for CI/CD pipeline integration. Exit code 1 on HIGH findings, 0 otherwise.
+- **Self-exclusion** — scanner automatically excludes its own skill directory to prevent flagging its own regex definitions.
+- **`.hipaaignore`** — project-level exclusion file (gitignore syntax) for suppressing known false positives.
+- **IDE/AI config file exclusions** — `.roomodes`, `.cursorrules`, `.windsurfrules`, `llms.txt`, `llms-full.txt`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `COPILOT.md` automatically skipped (contain pattern examples, not source code).
+
+### Changed
+- **`/hipaa-validate` frontmatter** — added `user-invocable: true`, `context: fork`, `agent: security-auditor`, `Bash` in `allowed-tools`.
+- **`/hipaa-validate` workflow** — pivoted from "manually execute regex patterns" to "run script, interpret results, suggest specific fixes."
+- **Documentation alignment** — updated hipaa-validate descriptions in README.md, ARCHITECTURE.md, skills-catalog.md, llms-full.txt to include all 8 check categories (was missing "temp file exposure" and "missing BAA references").
+- Skill count: 91 → 92 in package.json description.
+
+---
+
+## v1.4.2 — --local Scoping Fix, Leading Blank Lines Fix (2026-04-09)
+
+### Fixed
+- `--local` now runs only project-local install (no global re-install). Global install runs separately without `--local`.
+- Fixed leading blank lines in generated files (copilot-instructions.md, etc.) caused by `inject_section` and `inject_with_rules`.
+- Context-aware "Next steps" message (local vs global).
+
+### Changed
+- Updated KB docs: global-install-model.md, maintenance-sop.md to reflect `--local` scoping change.
+
+---
+
 ## v1.4.1 — Documentation Fix: --local Behavior (2026-04-09)
 
 ### Fixed

package/README.md

@@ -4,9 +4,9 @@
 
 [![CI](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Skills](https://img.shields.io/badge/skills-91-brightgreen)](app/skills/)
+[![Skills](https://img.shields.io/badge/skills-92-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-408%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-439%20passing-success)](tests/)
 
 ---
 
@@ -136,7 +136,7 @@ Replaces all symlinks with real files, inlines rules into CLAUDE.md, copies cons
 
 | Component | Count | Description |
 |-----------|-------|-------------|
-| `skills/` (task) | 28 | Slash commands: `/commit`, `/build`, `/deploy`, `/test`, `/skill-audit`, ... |
+| `skills/` (task) | 29 | Slash commands: `/commit`, `/build`, `/deploy`, `/test`, `/skill-audit`, `/hipaa-validate`, ... |
 | `skills/` (hybrid) | 31 | Slash commands with agent knowledge base |
 | `skills/` (knowledge) | 32 | Domain knowledge auto-loaded by agents |
 | `agents/` | 44 | Specialized agents across 10 categories |
@@ -227,6 +227,7 @@ ai-toolkit/
 | `/plugin-creator` | Scaffold an experimental plugin pack with manifest and optional modules | high |
 | `/skill-audit` | Scan skills/agents for security risks: dangerous patterns, secrets, permissions | medium |
 | `/cve-scan` | Scan project dependencies for known CVEs using native audit tools (npm, pip, composer, cargo, go, ruby, dart) | medium |
+| `/hipaa-validate` | Scan codebase for HIPAA compliance: PHI exposure, missing audit logging, unencrypted transmission/storage, access control gaps, temp file exposure, missing BAA references | medium |
 | `/analyze` | Code quality, complexity, and pattern analysis | medium |
 | `/fix` | Auto-fix lint/type errors | low |
 | `/build` | Build with issue detection | low |
@@ -589,7 +590,7 @@ All packs have `status: experimental`. Each has a `plugin.json` manifest and `RE
 
 | Feature | ai-toolkit | everything-claude-code | wshobson/agents | ruflo |
 |---------|---------------|----------------------|-----------------|-------|
-| Skills | 90 | 100+ | 146 | 20+ |
+| Skills | 91 | 100+ | 146 | 20+ |
 | Agents | 44 | 30+ | 112 | 20+ |
 | Machine-enforced constitution | **Yes** | No (docs only) | No | No |
 | Skill-scoped lifecycle hooks | **Yes** | No | No | No |

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "1.3.12",
+  "version": "1.5.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -102,7 +102,7 @@ Universal multi-agent system for software development. Works across all reposito
 
 ## Skills
 
-### Task Skills (28)
+### Task Skills (29)
 | Skill | Slash Command | Purpose |
 |-------|---------------|---------|
 | `commit` | `/commit` | Create well-structured git commits (Conventional Commits) |
@@ -133,6 +133,7 @@ Universal multi-agent system for software development. Works across all reposito
 | `plugin-creator` | `/plugin-creator` | Create experimental opt-in plugin packs with manifests, conventions, and optional modules |
 | `prd-to-issues` | `/prd-to-issues` | Break PRD into GitHub issues with vertical slices and HITL/AFK tagging |
 | `skill-audit` | `/skill-audit` | Scan skills and agents for security risks, dangerous patterns, secrets |
+| `hipaa-validate` | `/hipaa-validate` | Scan codebase for HIPAA compliance: PHI exposure, missing audit logging, unencrypted transmission/storage, access control gaps, temp file exposure, missing BAA references |
 
 ### Hybrid Skills (31)
 | Skill | Slash Command | Purpose |

package/app/skills/hipaa-validate/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: hipaa-validate
+description: "Validate code against HIPAA policy: PHI exposure, missing audit logging, unencrypted transmission/storage, access control gaps, temp file exposure, and missing BAA references"
+user-invocable: true
+effort: medium
+disable-model-invocation: true
+context: fork
+agent: security-auditor
+argument-hint: "[path] [--mode developer|compliance] [--severity high|warn] [--keywords term1,term2] [--output json]"
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# /hipaa-validate - HIPAA Compliance Scanner
+
+$ARGUMENTS
+
+Scan a codebase for HIPAA compliance issues using pattern-matching heuristics. Detects PHI exposure in logs, missing audit trails, unencrypted transmission/storage, hardcoded patient data, access control gaps, and missing Business Associate Agreement references. Read-only — never modifies files.
+
+**Regulation basis**: 45 CFR Parts 160, 162, 164 (HIPAA Administrative Simplification, as amended through March 26, 2013). Covers Security Rule (§164.302-318), Privacy Rule (§164.500-534), Breach Notification Rule (§164.400-414), and enforcement penalties (§160.400-426).
+
+## Usage
+
+```
+/hipaa-validate                              # Scan full project (developer mode — definitives only)
+/hipaa-validate src/                         # Scan specific path
+/hipaa-validate --mode compliance            # Full audit sweep including heuristic categories
+/hipaa-validate --severity high              # Filter to HIGH findings only
+/hipaa-validate --keywords member,enrollee   # Extend healthcare keyword list
+/hipaa-validate --output json                # Structured JSON output for CI integration
+```
+
+**Modes:**
+- `developer` (default): Categories 1, 3, 4, 7, 8 — definitive regex matches only, low false-positive rate, suited for daily use
+- `compliance`: All 8 categories — includes heuristic checks (Cat 2, 5, 6) for audit sweep coverage, suited for pre-audit sweeps
+
+**Severity filtering:** `--severity high` shows only HIGH findings, `--severity warn` shows HIGH + WARN. Default shows all.
+
+## What This Command Does
+
+1. **Run scanner script** — execute `scripts/hipaa_scan.py` with passed arguments
+2. **Interpret results** — analyze findings, add context, suggest specific fixes
+3. **Report** — present findings with file paths, line numbers, severity, confidence, and HIPAA rule citations
+
+## Steps
+
+### Step 1: Run the Scanner Script
+
+Execute the Python scanner with the user's arguments:
+
+```bash
+python3 "$(dirname "$0")/../app/skills/hipaa-validate/scripts/hipaa_scan.py" [path] [--mode developer|compliance] [--severity high|warn] [--keywords term1,term2] [--output json]
+```
+
+The script handles all scanning logic deterministically:
+- **Context gate** — identifies PHI-adjacent files via healthcare keyword matching
+- **Language detection** — detects project languages from manifest files
+- **8 check categories** — runs regex patterns and co-occurrence heuristics
+- **Deduplication** — removes duplicate findings (same file+line+category)
+- **`.hipaaignore` support** — honors exclusion patterns from project root
+- **`.hipaa-config` support** — reads `covered_vendors` for BAA checks
+
+If the script reports "No healthcare context detected", relay the message and suggest the `--keywords` flag with alternative terminology.
+
+If `--output json` is used, the script outputs structured JSON suitable for CI pipelines. The exit code is 1 if any HIGH findings exist, 0 otherwise.
+
+### Step 2: Interpret and Enrich Results
+
+For each finding from the script output:
+
+1. **Read the flagged file and line** to understand the actual code context
+2. **Add a specific fix suggestion** — not generic advice, but concrete code changes based on what you see
+3. **For heuristic findings** (confidence: "heuristic"), check if the concern is actually addressed elsewhere in the codebase (e.g., auth middleware at router level, audit logging in a shared module)
+4. **Mark confirmed false positives** and suggest adding them to `.hipaaignore`
+
+### Scanner Reference
+
+The script implements the following scan categories. This reference is provided so you can explain findings to the user and verify edge cases.
+
+**Modes:**
+- `developer` (default): Categories 1, 3, 4, 7, 8 — definitive regex matches only, low false-positive rate
+- `compliance`: All 8 categories — includes heuristic checks (Cat 2, 5, 6)
+
+**Default keywords**: `patient`, `diagnosis`, `medication`, `clinical`, `healthcare`, `medical`, `fhir`, `hl7`, `hipaa`, `phi`, `protected.health`, `health-record`, `health-plan`, `health-insurance`
+
+> **Note**: Bare `health` is deliberately excluded — it matches infrastructure health checks in nearly every codebase.
+
+**Built-in exclusions**: Binary files, lock files, vendored directories (`node_modules/`, `vendor/`, `.git/`, `dist/`, `build/`, `out/`, `.next/`). Test directories (`test/`, `tests/`, `__tests__/`, `spec/`, `fixtures/`, `mocks/`) are excluded for Category 4 only.
+
+Categories 1 and 2 scan the full project. Categories 3–8 scan only PHI-adjacent files.
+
+---
+
+#### Category 1: PHI in Logs/Console Output
+
+Scan the full project for log/print statements that reference PHI keywords.
+
+| Pattern | Severity | Language | Description |
+|---------|----------|----------|-------------|
+| `console\.log\(.*patient` | HIGH | JS/TS | Patient data in console |
+| `console\.\w+\(.*req\.body` | WARN | JS/TS | Raw request body may contain PHI |
+| `JSON\.stringify\(.*patient` | WARN | JS/TS | Full patient object serialization |
+| `print\(.*\b(patient\|ssn\|social.security)` | HIGH | Python | PHI in print statements |
+| `logging\.\w+\(.*\b(patient\|ssn\|mrn\|dob)` | HIGH | Python | PHI fields in logger calls |
+| `fmt\.Print.*\b(patient\|ssn\|mrn)` | HIGH | Go | PHI in fmt output |
+| `log\.\w+\(.*\b(patient\|ssn\|mrn)` | HIGH | Go/Any | PHI in log calls |
+| `System\.out\.print.*\b(patient\|ssn\|mrn)` | HIGH | Java | PHI in stdout |
+| `logger\.\w+\(.*\b(patient\|ssn\|mrn\|dob)` | HIGH | Java/Any | PHI fields in logger |
+| `puts.*\b(patient\|ssn\|mrn)` | HIGH | Ruby | PHI in puts |
+| `Rails\.logger.*\b(patient\|ssn\|mrn)` | HIGH | Ruby | PHI in Rails logger |
+| `Console\.Write.*\b(patient\|ssn\|mrn)` | HIGH | C# | PHI in Console output |
+| `_logger\.\w+\(.*\b(patient\|ssn\|mrn\|dob)` | HIGH | C# | PHI in ILogger calls |
+
+> **Language coverage note**: JS/TS patterns are the most comprehensive. Go, Ruby, and Java have baseline coverage for common log patterns. Contributions for additional language-specific patterns are welcome.
+
+**Minimum Necessary violations** (§164.502(b)):
+
+| Pattern | Severity | Language | Description |
+|---------|----------|----------|-------------|
+| `res\.(json\|send)\(.*patient` without field projection | WARN | JS/TS | Full patient object in API response |
+| `return.*patient` in route handler without field selection | WARN | Any | May expose unnecessary PHI fields |
+| `SELECT\s+\*.*FROM.*(patient\|member\|enrollee)` | WARN | SQL | SELECT * on PHI tables violates minimum necessary |
+| `JSON\.stringify\(.*patient` | WARN | JS/TS | Full patient object serialization |
+| `json\.dumps\(.*patient` | WARN | Python | Full patient object serialization |
+| `JsonConvert\.Serialize.*patient` | WARN | C# | Full patient object serialization |
+
+---
+
+#### Category 2: Missing Audit Logging
+
+*Compliance mode only. Heuristic — flags potential gaps, not definitive findings.*
+
+> **Developer mode**: This category is skipped. Run with `--mode compliance` to include audit gap checks.
+
+Scan the full project for files that handle PHI data operations but lack audit-related keywords.
+
+**PHI route file definition**: A file qualifies if it contains BOTH:
+1. A healthcare keyword from Step 0 (`patient`, `diagnosis`, `medication`, etc.)
+2. A data operation pattern: `router`, `app.get`, `app.post`, `app.put`, `app.delete`, `@RequestMapping`, `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`, `Model.find`, `Model.save`, `Model.update`, `db.query`, `db.execute`, `cursor.execute`, `repository.`, `findBy`, `save(`, `delete(`
+
+Files with a healthcare keyword but no data operation pattern are excluded.
+
+**Audit keywords** (co-occurrence check): `audit`, `AuditEvent`, `auditLog`, `logAccess`, `logEvent`, `createAuditEntry`, `recordAccess`, `ActivityLog`, `trail`, `writeAudit`
+
+| Pattern | Severity | Description |
+|---------|----------|-------------|
+| PHI route file without any audit keywords in same file | HIGH | §164.312(b) — POTENTIAL audit gap: verify audit controls exist in call chain |
+| CRUD operations on patient resources without audit keywords in same file | HIGH | POTENTIAL gap: all PHI access must be logged |
+| Admin operations without audit trail reference | WARN | POTENTIAL gap: administrative actions need recording |
+| Bulk data operations (`export`, `download`, `bulk`, `batch`) on PHI resources without audit keywords in same file | HIGH | POTENTIAL gap: mass PHI access must be tracked |
+
+> **Note**: This category uses co-occurrence heuristics — checking whether PHI route keywords and audit keywords appear in the same file. False positives are expected when audit logging is handled by middleware or a separate call chain. Use `.hipaaignore` to suppress confirmed false positives.
+
+See: [reference/hipaa-rules.md](reference/hipaa-rules.md) §164.312(b) for audit control requirements.
+
+---
+
+#### Category 3: Unencrypted PHI Transmission
+
+*Context-gated: scans PHI-adjacent files only.*
+
+| Pattern | Severity | Description |
+|---------|----------|-------------|
+| `http://` in API calls (not `localhost`/`127.0.0.1`) | HIGH | §164.312(e)(1) requires encryption in transit |
+| Missing TLS/SSL config in database connections | HIGH | Database connections must be encrypted |
+| `rejectUnauthorized:\s*false` | HIGH | TLS verification disabled |
+| `ws://` (WebSocket without TLS) | WARN | Unencrypted WebSocket may carry PHI |
+| Email sending without TLS config | WARN | PHI in email must use TLS |
+
+See: [reference/hipaa-rules.md](reference/hipaa-rules.md) §164.312(e)(1) for transmission security requirements.
+
+---
+
+#### Category 4: Hardcoded PHI/Test Data
+
+*Context-gated: scans PHI-adjacent files only.*
+
+**Built-in test directory exclusions**: Skip files in `test/`, `tests/`, `__tests__/`, `spec/`, `fixtures/`, `mocks/`, `__mocks__/`, `testdata/`, `test-data/` — test fixtures legitimately contain synthetic PHI.
+
+| Pattern | Severity | Description |
+|---------|----------|-------------|
+| `\d{3}-\d{2}-\d{4}` in PHI-adjacent source files | HIGH | Hardcoded SSNs |
+| MRN patterns near healthcare keywords | HIGH | Medical record numbers in code |
+| `\b\d{5}(-\d{4})?\b` near `zip\|postal\|address` keywords | WARN | ZIP codes in healthcare context (§164.514(b)(2)(i)(B)) |
+| Real-looking patient names in seed/fixture data | WARN | Use synthetic data generators |
+| Date of birth + name co-occurrence in same file | WARN | Combined identifiers = PHI |
+| Phone/email/IP regex matches in PHI-adjacent files | WARN | HIPAA identifiers in healthcare context |
+| `\d{3}[\s.-]?\d{3}[\s.-]?\d{4}` near `phone` keyword | WARN | Phone numbers in healthcare context |
+
+See: [reference/phi-identifiers.md](reference/phi-identifiers.md) for the full list of 18 HIPAA identifiers and detection patterns.
+
+---
+
+#### Category 5: Access Control Gaps
+
+*Context-gated: scans PHI-adjacent files only. Heuristic — flags potential gaps.*
+
+**Auth keywords** (co-occurrence check): `auth`, `authenticate`, `requireAuth`, `isAuthenticated`, `protect`, `guard`, `Authorize`, `login_required`, `Permission`
+
+| Pattern | Severity | Description |
+|---------|----------|-------------|
+| PHI route file without any auth keywords in same file | WARN | POTENTIAL access control gap — verify auth middleware covers these routes (§164.312(d)) |
+| `Access-Control-Allow-Origin:\s*\*` or `origin:\s*(true\|\*)` in PHI-adjacent files | HIGH | Unrestricted cross-origin access to PHI endpoints |
+| Routes marked `public`, `noAuth`, `anonymous` exposing PHI keywords | HIGH | PHI must require authentication |
+
+> **Note**: Auth middleware is commonly applied at router-level or app-level. The co-occurrence heuristic checks the same file only. False positives expected when auth is configured globally. Use `.hipaaignore` to suppress.
+
+See: [reference/hipaa-rules.md](reference/hipaa-rules.md) §164.312(a)(1) and §164.312(d) for access control and authentication requirements.
+
+---
+
+#### Category 6: Missing BAA References
+
+*Compliance mode only. Context-gated: scans PHI-adjacent files only.*
+
+> **Developer mode**: This category is skipped. Run with `--mode compliance` to include BAA checks.
+
+Instead of per-finding rows, emit a single **BAA Verification Checklist** in the compliance report:
+
+1. Grep PHI-adjacent files for HTTP client calls (`fetch(`, `axios.`, `requests.`, `http.Get`, `HttpClient`, `RestTemplate`, `urllib`). Extract external domains.
+2. Grep for cloud storage calls (`S3`, `GCS`, `BlobStorage`, `putObject`, `upload`). Note each service.
+3. Grep for cloud database connections (`mongodb+srv://`, `postgres://`, `mysql://`, `firestore`, `dynamodb`, `CosmosClient`, `MongoClient`, connection strings with cloud hostnames). Note each service.
+4. Grep for message queue / event streaming services (`SQS`, `SNS`, `RabbitMQ`, `redis://`, `kafka`, `EventBridge`, `PubSub`). Note each service.
+5. Grep for CDN references (`CloudFront`, `Cloudflare`, `Akamai`, `Fastly`, `cdn.`) serving PHI-adjacent paths. Note each service.
+6. Grep for observability / logging SDKs (`datadog`, `splunk`, `newrelic`, `sentry`, `logstash`, `elasticsearch`, `bugsnag`, `rollbar`). Note each SDK.
+7. Grep for analytics SDK calls (`analytics.`, `gtag`, `mixpanel`, `segment`, `amplitude`, `posthog`). Note each SDK.
+8. Read `.hipaa-config` at project root if it exists. Suppress vendors listed under `covered_vendors`.
+9. Emit one checklist row per unverified domain/service.
+
+**`.hipaa-config` format** (suppress known-covered vendors):
+```json
+{
+  "covered_vendors": ["aws", "twilio", "sendgrid", "stripe"]
+}
+```
+
+**Output format for compliance mode**:
+```
+### BAA Verification Checklist
+| Service/Domain | Pattern Detected | BAA Status |
+|----------------|-----------------|------------|
+| AWS S3 | `putObject` in src/storage/patient-files.ts | ✓ covered (covered_vendors) |
+| sendgrid.com | `axios.post` in src/notifications/email.ts | ⚠️ verify BAA exists |
+| analytics.google.com | `gtag` in src/components/Dashboard.tsx | ❌ verify no PHI flows here |
+```
+
+> **Note**: This is a documentation checklist, not a legal review. Items marked ⚠️ or ❌ require human verification, not code changes.
+
+---
+
+#### Category 7: Encryption at Rest
+
+*Context-gated: scans PHI-adjacent files only. Developer mode.*
+
+Detects PHI storage patterns without encryption references. Per §164.312(a)(2)(iv), ePHI must be encrypted when stored.
+
+| Pattern | Severity | Description |
+|---------|----------|-------------|
+| `encrypt\s*[:=]\s*false` in database config files | HIGH | §164.312(a)(2)(iv) — Encryption explicitly disabled |
+| File write operations (`writeFile`, `fs.write`, `open(.*w`, `File.Create`) in PHI-adjacent code without encryption references | WARN | PHI written to disk may lack encryption at rest |
+| Database connection without `ssl`, `encrypt`, or `tls` keywords in PHI-adjacent config | WARN | Database storing PHI should enforce encrypted connections |
+| `localStorage.setItem` or `sessionStorage.setItem` with PHI keywords | HIGH | Browser storage is unencrypted — PHI must not be stored client-side without encryption |
+| `SharedPreferences` or `UserDefaults` with PHI keywords | HIGH | Mobile local storage is unencrypted by default |
+
+See: [reference/hipaa-rules.md](reference/hipaa-rules.md) §164.312(a)(2)(iv) for encryption requirements.
+
+---
+
+#### Category 8: PHI Temp File Exposure
+
+*Context-gated: scans PHI-adjacent files only. Developer mode.*
+
+Detects temporary file creation in PHI-adjacent code without secure deletion. Per §164.310(d)(2)(iii), media containing PHI must be sanitized before reuse or disposal.
+
+| Pattern | Severity | Description |
+|---------|----------|-------------|
+| `/tmp/` or `tempfile\.` or `os\.tmpdir\(\)` or `Path\.GetTempPath` in PHI-adjacent code | WARN | §164.310(d)(2)(iii) — Temp files with PHI must be securely deleted |
+| `mktemp` or `NamedTemporaryFile` or `createTempFile` near PHI keywords | WARN | Verify temp files are cleaned up after use |
+| Cache directory writes (`cache/`, `.cache`, `Cache.set`) with PHI keywords | WARN | Cached PHI must be encrypted or purged on schedule |
+
+See: [reference/hipaa-rules.md](reference/hipaa-rules.md) §164.310(d)(2)(iii) for disposal requirements.
+
+### Step 3: Compile and Report
+
+Present the scanner output to the user. Sort by severity (HIGH first), then by file path.
+
+## Output Format
+
+```markdown
+## HIPAA Validation Report
+
+### Summary
+| Metric | Value |
+|--------|-------|
+| Mode | developer / compliance |
+| PHI-adjacent files | N |
+| Files scanned | N |
+| Categories run | 1,3,4,7,8 (developer) / 1,2,3,4,5,6,7,8 (compliance) |
+| Severity HIGH | N |
+| Severity WARN | N |
+
+### Findings
+
+#### [HIGH] src/api/patients.ts:42
+Category: PHI in Logs
+Confidence: definitive (regex match)
+Pattern: `console.log(patient.name)`
+HIPAA Rule: §164.502(b) — Minimum Necessary Standard
+Fix: Replace with `safeLog()` or remove PHI from log output
+
+#### [HIGH] src/routes/patient-api.ts:15
+Category: Missing Audit Logging
+Confidence: heuristic (co-occurrence check — may be false positive)
+Pattern: PHI route file without audit keywords
+HIPAA Rule: §164.312(b) — Audit Controls
+Fix: Verify audit logging exists in call chain; add AuditEvent creation if missing
+
+#### [WARN] src/services/patient-sync.ts:88
+Category: Unencrypted PHI Transmission
+Confidence: definitive (regex match)
+Pattern: `http://external-api.example.com/patients`
+HIPAA Rule: §164.312(e)(1) — Transmission Security
+Fix: Use HTTPS for all PHI transmission
+```
+
+**Confidence values**:
+- `definitive` — Categories 1, 3, 4, 7, 8: regex matched actual code
+- `heuristic` — Categories 2, 5, 6: co-occurrence/absence check, may be false positive
+
+This distinction helps compliance officers prioritize immediate remediation (definitive) vs. investigation (heuristic).
+
+## Rules
+
+- **Read-only**: Never modify any files. Report findings only.
+- **HIPAA rule citation**: Every finding must reference a specific HIPAA section (§ number).
+- **Skip non-source files**: Binary files, lock files (`*.lock`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`), vendored directories (`node_modules/`, `vendor/`, `.git/`, `dist/`, `build/`, `out/`, `.next/`).
+- **Respect `.hipaaignore`**: Honor exclusion patterns in the project's `.hipaaignore` file.
+- **No false confidence**: Clearly label heuristic findings as `POTENTIAL` and mark confidence as `heuristic`.
+- **Context before identifiers**: Always run the healthcare keyword context gate before applying PHI identifier regex patterns (Category 4) to avoid false positives.
+- **Warn on missing secrets management**: Flag PHI-adjacent config files without `.env` or secret manager references.
+- **No auto-fix in v1**: Auto-fixing HIPAA issues requires project-specific knowledge of logging/audit infrastructure. Planned for v2.
+
+## Reference Documents
+
+- [reference/hipaa-rules.md](reference/hipaa-rules.md) — HIPAA Security Rule, Privacy Rule, and Breach Notification Rule mapped to technical controls
+- [reference/phi-identifiers.md](reference/phi-identifiers.md) — The 18 HIPAA identifiers with detection patterns and detectability status