@softspark/ai-toolkit 4.22.1 → 4.23.0

package/CHANGELOG.md

@@ -7,6 +7,35 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.23.0 — a compliance scanner that says nothing must say why (2026-08-06)
+
+### Fixed
+
+- **`hipaa-validate` scanned a manifest-less project silently clean.** Category
+  1, 3, 4 and 7 patterns are language-tagged and fire only for a detected
+  language, and detection read manifest files only. A directory of Python with
+  PHI in its loggers therefore reported `HIGH: 0` while every Python rule sat
+  unused — the worst possible output for a compliance tool, because zero reads
+  as compliant. Found by the post-release SOP on v4.22.1.
+
+  Detection now falls back to the extensions of the files being scanned when no
+  manifest is present. **Manifests still win**, so a project that already
+  declared itself keeps exactly the behaviour it had.
+
+### Changed
+
+- **The scan summary reports how the language was decided.** A new
+  `language_detection` field says `manifest`, `file extensions (no manifest
+  found)`, or `none`. When it is `none` the text report writes to stderr that
+  language-tagged patterns did not run and that a zero-finding result means
+  unscanned rather than compliant.
+
+  **Upgrade note:** a project scanned without a manifest may now report HIGH
+  findings where v4.22.x reported none. Those findings were always there. A CI
+  job gating on the exit code can start failing on real PHI exposure.
+
+---
+
 ## v4.22.1 — nine skills, not four, could not find their own scripts (2026-08-06)
 
 v4.22.0 claimed to fix four skills whose documented script path never resolved.

package/README.md

@@ -6,7 +6,16 @@
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-109-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1513%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1516%20passing-success)](tests/)
+
+## What's New in v4.23.0
+
+**v4.23.0** — `hipaa-validate` scanned a project without a manifest silently
+clean: its language-tagged patterns never ran, and the report said `HIGH: 0`.
+Zero reads as compliant. Detection now falls back to file extensions, the summary
+says how the language was decided, and an undecidable run warns that a zero means
+unscanned. Manifest-declaring projects are unaffected. Found by the post-release
+SOP, not by a user.
 
 ## What's New in v4.22.1
 

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

@@ -3,7 +3,7 @@
   "name": "ai-toolkit",
   "displayName": "AI Toolkit",
   "description": "Professional-grade engineering skills, agents, rules, and lifecycle guardrails for Claude Code, Claude Chat, and Cowork.",
-  "version": "4.22.1",
+  "version": "4.23.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

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

@@ -161,6 +161,9 @@ This distinction helps compliance officers prioritize immediate remediation (def
 
 ## Gotchas
 
+- **Check `language_detection` in the summary before trusting a zero.** Category 1, 3, 4 and 7 patterns are language-tagged and only fire for a detected language. Manifests decide first (`pyproject.toml`, `package.json`, `go.mod`, …); without one the scanner falls back to file extensions. If it reports `languages: ["any"]` with `language_detection: "none"`, the language rules never ran and `HIGH: 0` means *unscanned*, not *compliant* — the scanner prints that warning to stderr, so a run whose stderr is discarded loses it.
+- Scanning a monorepo package or a subdirectory can put you below the manifest. The extension fallback covers the common case, but a directory of `.sql`, `.yaml` or templates resolves to no language at all — scan from the level that holds the manifest.
+
 - Test fixtures and seed data often contain **synthetic** PHI that looks real (SSN-shaped IDs, formatted phone numbers, sample email addresses). Flag them but lower severity — production code handling the same patterns is the actual risk.
 - HIPAA §164.312(b) requires audit logging but does not specify a format. "Logs exist" is not evidence of compliance — the logs must capture WHO (authenticated user), WHAT (action), WHEN (timestamp), WHERE (resource), and they must be immutable (append-only or write-once storage).
 - Encryption-at-rest varies silently by storage layer. RDS auto-encrypts new volumes since 2017, but older DB snapshots may not be; S3 bucket policies can override instance-level encryption. Treat "encryption enabled" as a claim to verify with the cloud provider, not a state to trust.

package/app/skills/hipaa-validate/scripts/hipaa_scan.py

@@ -302,8 +302,24 @@ def context_gate(files: list[Path], keywords: list[str],
 # Language detection (Step 1)
 # ---------------------------------------------------------------------------
 
-def detect_languages(root: Path) -> set[str]:
-    """Detect project languages from manifest files."""
+def detect_languages(root: Path, files: list[Path] | None = None) -> tuple[set[str], str]:
+    """Detect project languages. Returns (languages, how_they_were_detected).
+
+    Manifest files decide when present. When none is found, fall back to the
+    extensions of the files actually being scanned.
+
+    The fallback exists because language-tagged patterns fire only when the
+    project language includes the tag, so a manifest-less directory of Python
+    scanned clean while every Python rule sat unused — and the report said
+    `HIGH: 0`, which reads as compliant rather than unscanned. Silence is the
+    worst possible output for a compliance tool. A monorepo package, a scan
+    pointed at a subdirectory, or a service whose manifest lives one level up
+    all hit this.
+
+    Manifests still win: a project that declares itself keeps exactly the
+    behaviour it had, so upgrading changes nothing for anyone who was already
+    being scanned properly.
+    """
     langs = set()
     for indicator, lang in LANGUAGE_INDICATORS.items():
         if "*" in indicator:
@@ -314,7 +330,20 @@ def detect_languages(root: Path) -> set[str]:
         else:
             if (root / indicator).exists():
                 langs.add(lang)
-    return langs or {"any"}
+    if langs:
+        return langs, "manifest"
+
+    if files:
+        ext_to_lang: dict[str, set[str]] = {}
+        for lang, exts in LANG_EXTENSIONS.items():
+            for ext in exts:
+                ext_to_lang.setdefault(ext, set()).add(lang)
+        for f in files:
+            langs |= ext_to_lang.get(f.suffix, set())
+        if langs:
+            return langs, "file extensions (no manifest found)"
+
+    return {"any"}, "none — language-tagged patterns were skipped"
 
 
 # ---------------------------------------------------------------------------
@@ -616,7 +645,8 @@ def format_text_report(findings: list[dict], mode: str,
 
 def format_json_report(findings: list[dict], mode: str,
                        phi_count: int, scanned_count: int,
-                       categories_run: list[int], languages: list[str]) -> str:
+                       categories_run: list[int], languages: list[str],
+                       language_source: str = "manifest") -> str:
     """Format findings as structured JSON for CI integration."""
     high_count = sum(1 for f in findings if f["severity"] == "HIGH")
     warn_count = sum(1 for f in findings if f["severity"] == "WARN")
@@ -628,6 +658,7 @@ def format_json_report(findings: list[dict], mode: str,
             "files_scanned": scanned_count,
             "categories_run": sorted(categories_run),
             "languages": sorted(languages),
+            "language_detection": language_source,
             "high": high_count,
             "warn": warn_count,
             "total": len(findings),
@@ -723,8 +754,9 @@ def main() -> None:
               file=sys.stderr)
         print("Consider narrowing the scan path for targeted results.", file=sys.stderr)
 
-    # Step 1: Detect languages
-    languages = detect_languages(root)
+    # Step 1: Detect languages. Categories 1-2 scan everything, so the extension
+    # fallback looks at all collected files, not just the PHI-adjacent subset.
+    languages, lang_source = detect_languages(root, all_files)
 
     # Step 2: Run categories
     findings: list[dict] = []
@@ -789,10 +821,18 @@ def main() -> None:
     if args.output == "json":
         print(format_json_report(findings, args.mode, phi_count,
                                  scanned_count, categories_run,
-                                 sorted(languages)))
+                                 sorted(languages), lang_source))
     else:
         print(format_text_report(findings, args.mode, phi_count,
                                  scanned_count, categories_run))
+        if languages == {"any"}:
+            # Never let an unscanned run read as a clean one.
+            print("\nWARNING: no project language identified "
+                  f"({lang_source}).", file=sys.stderr)
+            print("Language-tagged patterns (Python, JS/TS, Go, Java, Ruby, C#) "
+                  "did NOT run.", file=sys.stderr)
+            print("A zero-finding result here means unscanned, not compliant. "
+                  "Scan from the directory holding the manifest.", file=sys.stderr)
 
     # Exit code: non-zero if HIGH findings
     high_count = sum(1 for f in findings if f["severity"] == "HIGH")

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.22.1",
+  "version": "4.23.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.22.1",
+  "version": "4.23.0",
   "description": "AI coding toolkit: 109 skills, 44 agents, 12 developer-tool integrations, recoverable native tool-output filtering, Claude Chat/Cowork export, safety constitution, SARIF audit, and signed npm provenance.",
   "keywords": [
     "claude",