@softspark/ai-toolkit 4.20.0 → 4.22.0

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

@@ -48,7 +48,7 @@ Scan a codebase for HIPAA compliance issues using pattern-matching heuristics. D
 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]
+python3 ${CLAUDE_SKILL_DIR}/scripts/hipaa_scan.py [path] [--mode developer|compliance] [--severity high|warn] [--keywords term1,term2] [--output json]
 ```
 
 The script handles all scanning logic deterministically:
@@ -65,6 +65,9 @@ If `--output json` is used, the script outputs structured JSON suitable for CI p
 
 ### Step 2: Interpret and Enrich Results
 
+Read [reference/scanner-categories.md](reference/scanner-categories.md) once before
+starting — you cannot judge a heuristic finding without the pattern that produced it.
+
 For each finding from the script output:
 
 1. **Read the flagged file and line** to understand the actual code context
@@ -74,226 +77,27 @@ For each finding from the script output:
 
 ### 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\|logger\|pprint)\.\w+\(.*\b(patient\|ssn\|mrn\|dob)` | HIGH | Python | PHI in logger/named logger/pprint output |
-| `print\(.*request\.(data\|json\|form\|POST\|body)` | WARN | Python | Raw request body may contain PHI (Django/Flask/FastAPI) |
-| `(logging\|logger)\.\w+\(.*request\.(data\|json\|form\|POST\|body)` | WARN | Python | Raw request body in logger |
-| `\brepr\(.*\b(patient\|ssn\|mrn)` | WARN | Python | repr() may expose PHI fields |
-| `\bvars\(.*\b(patient\|ssn\|mrn)` | WARN | Python | vars() dumps all PHI fields |
-| `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 and Python 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(`, `@app.route`, `@blueprint.route`, `@api_view`, `ViewSet`, `APIView`, `\bsession.(query|add|execute|delete|merge)\b` (word-anchored — SQLAlchemy only, avoids matching Express `req.session.save`)
-
-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 | Language | Description |
-|---------|----------|----------|-------------|
-| `http://` in API calls (not `localhost`/`127.0.0.1`) | HIGH | Any | §164.312(e)(1) requires encryption in transit |
-| Missing TLS/SSL config in database connections | HIGH | Any | Database connections must be encrypted |
-| `rejectUnauthorized:\s*false` | HIGH | Any | TLS verification disabled |
-| `ws://` (WebSocket without TLS) | WARN | Any | Unencrypted WebSocket may carry PHI |
-| `verify\s*=\s*False` | HIGH | Python | TLS verification disabled (requests/httpx) |
-| `InsecureRequestWarning` | WARN | Python | TLS warning suppressed |
-| `[,(]\s*ssl\s*=\s*False\b` | HIGH | Python | SSL disabled in connector call (anchored to arg position to avoid matching `is_ssl_enabled = False`) |
-| `ssl\.CERT_NONE` | HIGH | Python | TLS certificate verification disabled (anchored to `ssl.` module) |
-| `check_hostname\s*=\s*False` | HIGH | Python | TLS hostname verification disabled |
-| `urllib3\.disable_warnings` | WARN | Python | TLS warnings suppressed (urllib3) |
-| `SECURE_SSL_REDIRECT\s*=\s*False` | WARN | Python | Django HTTPS redirect disabled (commonly False in dev settings — verify production config) |
-| `NODE_TLS_REJECT_UNAUTHORIZED.*0` | HIGH | JS/TS | TLS rejection disabled globally |
-
-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`, `permission_required`, `LoginRequiredMixin`, `PermissionRequiredMixin`, `IsAuthenticated`, `Depends`, `Security`
-
-**Data operation patterns** (Python frameworks): `@app.route`, `@blueprint.route`, `@api_view`, `ViewSet`, `APIView`, `cursor.execute`, `\bsession.(query|execute)\b` (word-anchored — SQLAlchemy only)
-
-| Pattern | Severity | Language | Description |
-|---------|----------|----------|-------------|
-| PHI route file without any auth keywords in same file | WARN | Any | 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 | Any | Unrestricted cross-origin access to PHI endpoints |
-| Routes marked `public`, `noAuth`, `anonymous` exposing PHI keywords | HIGH | Any | PHI must require authentication |
-| `permission_classes\s*=.*AllowAny` | WARN | Python | DRF AllowAny — verify no PHI exposed |
-
-> **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 | Language | Description |
-|---------|----------|----------|-------------|
-| `encrypt\s*[:=]\s*false` in database config files | HIGH | Any | §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 | Any | PHI written to disk may lack encryption at rest |
-| Database connection without `ssl`, `encrypt`, or `tls` keywords in PHI-adjacent config | WARN | Any | Database storing PHI should enforce encrypted connections |
-| `localStorage.setItem` or `sessionStorage.setItem` with PHI keywords | HIGH | JS/TS | Browser storage is unencrypted — PHI must not be stored client-side without encryption |
-| `SharedPreferences` or `UserDefaults` with PHI keywords | HIGH | Java/Any | Mobile local storage is unencrypted by default |
-| `pickle\.(dump\|dumps)\(` with PHI keywords | HIGH | Python | pickle serialization is unencrypted — PHI must be encrypted at rest |
-| `shelve\.open\(` with PHI keywords | HIGH | Python | shelve storage is unencrypted — PHI must be encrypted at rest |
-
-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.
+The eight scan categories are implemented in `scripts/hipaa_scan.py`. The pattern
+tables, severities, per-language coverage and rule citations live in
+[reference/scanner-categories.md](reference/scanner-categories.md).
+
+Read that file once, in full, before enriching findings in Step 2 — it is what lets
+you explain *why* a line matched and judge whether a heuristic hit is a false
+positive. The scan itself does not need it; the script already holds the patterns.
+
+| # | Category | Scope | Mode |
+|---|----------|-------|------|
+| 1 | PHI in logs / console output (+ minimum-necessary violations) | full project | developer |
+| 2 | Missing audit logging | full project | compliance only, heuristic |
+| 3 | Unencrypted transmission | PHI-adjacent | developer |
+| 4 | Hardcoded PHI test data | PHI-adjacent | developer |
+| 5 | Access control gaps | PHI-adjacent | compliance only, heuristic |
+| 6 | Missing BAA references | PHI-adjacent | compliance only, heuristic |
+| 7 | Encryption at rest | PHI-adjacent | developer |
+| 8 | PHI temp file exposure | PHI-adjacent | developer |
+
+Categories 1 and 2 scan the full project; categories 3–8 scan only PHI-adjacent
+files. Compliance mode adds the heuristic categories 2, 5 and 6 to the developer set.
 
 ### Step 3: Compile and Report
 

package/app/skills/hipaa-validate/reference/scanner-categories.md

@@ -0,0 +1,224 @@
+# HIPAA Scanner Categories
+
+## 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\|logger\|pprint)\.\w+\(.*\b(patient\|ssn\|mrn\|dob)` | HIGH | Python | PHI in logger/named logger/pprint output |
+| `print\(.*request\.(data\|json\|form\|POST\|body)` | WARN | Python | Raw request body may contain PHI (Django/Flask/FastAPI) |
+| `(logging\|logger)\.\w+\(.*request\.(data\|json\|form\|POST\|body)` | WARN | Python | Raw request body in logger |
+| `\brepr\(.*\b(patient\|ssn\|mrn)` | WARN | Python | repr() may expose PHI fields |
+| `\bvars\(.*\b(patient\|ssn\|mrn)` | WARN | Python | vars() dumps all PHI fields |
+| `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 and Python 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(`, `@app.route`, `@blueprint.route`, `@api_view`, `ViewSet`, `APIView`, `\bsession.(query|add|execute|delete|merge)\b` (word-anchored — SQLAlchemy only, avoids matching Express `req.session.save`)
+
+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: [hipaa-rules.md](hipaa-rules.md) §164.312(b) for audit control requirements.
+
+---
+
+### Category 3: Unencrypted PHI Transmission
+
+*Context-gated: scans PHI-adjacent files only.*
+
+| Pattern | Severity | Language | Description |
+|---------|----------|----------|-------------|
+| `http://` in API calls (not `localhost`/`127.0.0.1`) | HIGH | Any | §164.312(e)(1) requires encryption in transit |
+| Missing TLS/SSL config in database connections | HIGH | Any | Database connections must be encrypted |
+| `rejectUnauthorized:\s*false` | HIGH | Any | TLS verification disabled |
+| `ws://` (WebSocket without TLS) | WARN | Any | Unencrypted WebSocket may carry PHI |
+| `verify\s*=\s*False` | HIGH | Python | TLS verification disabled (requests/httpx) |
+| `InsecureRequestWarning` | WARN | Python | TLS warning suppressed |
+| `[,(]\s*ssl\s*=\s*False\b` | HIGH | Python | SSL disabled in connector call (anchored to arg position to avoid matching `is_ssl_enabled = False`) |
+| `ssl\.CERT_NONE` | HIGH | Python | TLS certificate verification disabled (anchored to `ssl.` module) |
+| `check_hostname\s*=\s*False` | HIGH | Python | TLS hostname verification disabled |
+| `urllib3\.disable_warnings` | WARN | Python | TLS warnings suppressed (urllib3) |
+| `SECURE_SSL_REDIRECT\s*=\s*False` | WARN | Python | Django HTTPS redirect disabled (commonly False in dev settings — verify production config) |
+| `NODE_TLS_REJECT_UNAUTHORIZED.*0` | HIGH | JS/TS | TLS rejection disabled globally |
+
+See: [hipaa-rules.md](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: [phi-identifiers.md](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`, `permission_required`, `LoginRequiredMixin`, `PermissionRequiredMixin`, `IsAuthenticated`, `Depends`, `Security`
+
+**Data operation patterns** (Python frameworks): `@app.route`, `@blueprint.route`, `@api_view`, `ViewSet`, `APIView`, `cursor.execute`, `\bsession.(query|execute)\b` (word-anchored — SQLAlchemy only)
+
+| Pattern | Severity | Language | Description |
+|---------|----------|----------|-------------|
+| PHI route file without any auth keywords in same file | WARN | Any | 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 | Any | Unrestricted cross-origin access to PHI endpoints |
+| Routes marked `public`, `noAuth`, `anonymous` exposing PHI keywords | HIGH | Any | PHI must require authentication |
+| `permission_classes\s*=.*AllowAny` | WARN | Python | DRF AllowAny — verify no PHI exposed |
+
+> **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: [hipaa-rules.md](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 | Language | Description |
+|---------|----------|----------|-------------|
+| `encrypt\s*[:=]\s*false` in database config files | HIGH | Any | §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 | Any | PHI written to disk may lack encryption at rest |
+| Database connection without `ssl`, `encrypt`, or `tls` keywords in PHI-adjacent config | WARN | Any | Database storing PHI should enforce encrypted connections |
+| `localStorage.setItem` or `sessionStorage.setItem` with PHI keywords | HIGH | JS/TS | Browser storage is unencrypted — PHI must not be stored client-side without encryption |
+| `SharedPreferences` or `UserDefaults` with PHI keywords | HIGH | Java/Any | Mobile local storage is unencrypted by default |
+| `pickle\.(dump\|dumps)\(` with PHI keywords | HIGH | Python | pickle serialization is unencrypted — PHI must be encrypted at rest |
+| `shelve\.open\(` with PHI keywords | HIGH | Python | shelve storage is unencrypted — PHI must be encrypted at rest |
+
+See: [hipaa-rules.md](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: [hipaa-rules.md](hipaa-rules.md) §164.310(d)(2)(iii) for disposal requirements.

package/app/skills/pr/SKILL.md

@@ -28,7 +28,7 @@ Create a GitHub pull request.
 Generate a structured PR summary from the commit history before writing the PR description:
 
 ```bash
-python3 "$(dirname "$0")/scripts/pr-summary.py" [base_branch]
+python3 ${CLAUDE_SKILL_DIR}/scripts/pr-summary.py [base_branch]
 # Default base branch: main
 # Example: python3 scripts/pr-summary.py develop
 ```

package/app/skills/review/SKILL.md

@@ -19,6 +19,23 @@ Reviews code changes for quality and issues.
 
 - Changes: !`git diff --stat main...HEAD 2>/dev/null || git diff --cached --stat 2>/dev/null || echo "no changes detected"`
 
+## Signal Collection (never stop at the first red)
+
+Collect every failing signal up front, then review the diff in full **anyway**:
+
+| Signal | How to read it |
+|--------|----------------|
+| Merge conflict with base | `gh pr view --json mergeable,mergeStateStatus` or `git merge-tree` |
+| Failing CI checks | `gh pr checks` or the platform equivalent |
+| Lint / typecheck failure | the project's own commands |
+
+Each failing signal becomes a `blocker` finding. **None of them ends the run.**
+
+A review that aborts on the first red signal spends the whole cycle repeating what
+the tracker already displayed, while the finding that would have told the author
+something new never gets written. One invocation produces the most complete picture
+of the change that it can.
+
 ## Automated Diff Analysis
 
 Before starting manual review, run the diff analyzer script to get a structured risk assessment:
@@ -58,8 +75,8 @@ Each reviewer should report findings independently. Do NOT modify files.
 
 After all reviewers complete:
 1. Synthesize findings into unified Code Review Report
-2. Prioritize by severity (Critical > Major > Minor)
-3. Issue verdict: APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION
+2. Prioritize by severity (blocker > major > minor > nit)
+3. Issue verdict per the verdict rule below — not by impression
 
 > **When to use**: PRs with >5 files changed, cross-module changes, security-sensitive code.
 > **READ-ONLY**: No teammate should modify files during review.
@@ -101,12 +118,15 @@ After all reviewers complete:
 - [ ] A08: Integrity checks on deserialized data, CI/CD pipeline safety
 - [ ] A09: Security-relevant events logged (without PII)
 - [ ] A10: External URL handling validates scheme/host (SSRF prevention)
+- [ ] Cross-scope replay: can an identifier from one tenant/user/org be replayed in another?
+- [ ] Fails closed wherever the path affects security, money, or data retention
 
 ### API / Contract Changes
 - [ ] Backward compatibility preserved (no silent breaking changes)
 - [ ] API versioning updated if contract changed
 - [ ] Schema validation on request/response
 - [ ] Error responses follow project convention
+- [ ] Wire-level contracts checked, not just code signatures: HTTP routes, webhook payloads, event/queue schemas
 
 ### Concurrency / Async
 - [ ] Shared mutable state protected (locks, atomics, channels)
@@ -131,6 +151,26 @@ After all reviewers complete:
 - [ ] Edge cases covered
 - [ ] Mocks appropriate
 
+## Severity & Verdict
+
+| Tier | Meaning | Merge impact |
+|------|---------|--------------|
+| `blocker` | Causes damage: data loss, security hole, money, corruption | Blocks merge, no exceptions |
+| `major` | Real defect that will bite in production | Blocks merge unless waived in writing |
+| `minor` | Should be fixed, not worth blocking on | Does not block |
+| `nit` | Polish, taste, style | Does not block |
+
+**Verdict rule** — apply it mechanically, do not negotiate with yourself:
+
+- any `blocker` → `REQUEST_CHANGES`
+- any `major` without a documented waiver (who waived it, why, what the follow-up is) → `REQUEST_CHANGES`
+- only `minor` / `nit` → `APPROVE`
+- the change cannot be classified from the diff → `NEEDS_DISCUSSION`, and state what would resolve it
+
+Severity describes impact, confidence describes certainty — they are independent
+axes. A finding with confidence < 6 is reported at the tier its evidence supports
+and is never promoted to `blocker` on suspicion alone.
+
 ## Output Format
 
 ```markdown
@@ -145,9 +185,9 @@ After all reviewers complete:
 
 ### Findings
 
-#### Critical
+#### Blocker
 - **[file:line]**: [issue]
-  - Severity: critical | Confidence: [1-10]
+  - Severity: blocker | Confidence: [1-10]
   - Evidence: [specific code reference and reasoning]
   - Suggested fix: [code]
 
@@ -181,6 +221,11 @@ After all reviewers complete:
 
 ### Verdict
 [APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION]
+
+State which clause of the verdict rule produced it, e.g.
+"REQUEST_CHANGES — 1 blocker (auth.ts:88)" or
+"APPROVE — 2 minor, 1 nit, no blocker or major".
+Waived majors must name the waiver and the follow-up.
 ```
 
 ## Common Rationalizations