fix: the engine only knew Node (3.5.1)

.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
   "name": "clean-code-toolkit",
-  "version": "3.5.0",
+  "version": "3.5.1",
   "description": "Clean-code and product-handoff tools for AI-assisted builders.",
   "owner": {
     "name": "Tarik Moody"
@@ -10,7 +10,7 @@
     {
       "name": "clean-code-toolkit",
       "description": "Review code, assess product readiness, refactor safely, and prepare a developer handoff.",
-      "version": "3.5.0",
+      "version": "3.5.1",
       "author": {
         "name": "Tarik Moody"
       },

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "clean-code-toolkit",
-  "version": "3.5.0",
+  "version": "3.5.1",
   "description": "Practical clean-code, product-readiness, and developer-handoff workflows for AI-assisted projects.",
   "author": {
     "name": "Tarik Moody"

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 3.5.1
+
+Five defects, and one thing underneath all of them: the engine only really knew Node. Two of these were saying something false about any repository a user ran them on today.
+
+**`auth-2` was wrong about half the time it spoke.** On a live application it reported "18 of 25 request handlers never mention an auth check" as a HIGH finding. At least 14 of the flagged files were authenticated, by three mechanisms a word search could not see: middleware that guards every route not on a public list, webhook routes that verify a cryptographic signature because the caller is a machine and cannot hold a browser session, and routes that compare a shared secret from the environment. The check now recognizes all three. When it finds request middleware it stops asserting the handlers are unguarded and instead reports, at LOW, that they rely on the middleware, naming the file and listing the public route patterns it found so a person can confirm the matcher in about a minute. On the same application the finding is now 9 of 25, and each of the 9 is genuinely middleware-dependent. `auth-3`, which found a real fail-open owner check, is unchanged. See `docs/decisions/006`.
+
+**`package_json()` broke every repository that is not JavaScript.** A monorepo change in 3.2.3 made it always return a dict of empty sections, and that dict is truthy, so all seven `if pkg:` callers thought a manifest existed. A Go project was reported as `languages: ['go', 'javascript']` and told, at HIGH, "package.json exists but does not define a `test` script", about a file that was not there. It now returns nothing when there is no manifest and no workspace members.
+
+**Python and Go fixtures, and the two failures they found immediately.** Every meaningful fixture in the suite was a JavaScript repository, which is why none of the above was caught. Adding a FastAPI service and a Go service surfaced two more on the first run: dependencies declared PEP 621 style in `pyproject.toml`, quoted inside an array, were parsed as nothing, so `fastapi-users` was invisible and the service was told it had no authentication at all. Both call sites now share one dependency-name parser. And a health route declared in code, `@app.get("/health")` or `r.Get("/health", ...)`, which is how every framework except Next.js declares one, was invisible to a check that only globbed file paths. It now reads code declarations too, marked as weak evidence because a path in a string is not proof the route answers.
+
+**Lint and typecheck steps outside Node.** `ci-3` knew `eslint`, `ruff`, `flake8`, `pylint`, `tsc` and `typecheck`. A pipeline running `mypy app` was told it had no lint or typecheck step. Added: `mypy`, `pyright`, `black --check`, `golangci-lint`, `go vet`, `gofmt`, `staticcheck`, `rubocop`, `clippy`, `cargo fmt`, `dotnet format`, `ktlint`, `detekt`, `checkstyle`, `phpstan`, `psalm`, `biome`, `oxlint`, `prettier --check`.
+
+**The "any language" claim is retired.** `SKILL.md` said "It works on any git repo regardless of language/framework." Repository-level checks do. Stack-specific ones are strongest on Node and Next.js, good on Python, and have no rules for Go, Rust, Ruby, Java, PHP or C#. Both `SKILL.md` and `README.md` now say which is which and name the four specific gaps. This toolkit's whole thesis is that a tool must not overstate what it checked; that sentence was the tool overstating where it looked. See `docs/decisions/007`.
+
+**The two readiness skills are distinguishable at a glance.** Both descriptions used to open with audit and production-readiness language, and a tester reported that Claude could not reliably choose between them. They now open with the actual split: `prod-readiness-coach` scans repository controls and scripts, `product-readiness-review` judges user journeys and product behavior. The coach's description also lists Access Control, which has been one of its nine categories since 3.5.0 and was missing from the list.
+
+**Tests now have to prove a check stays quiet.** Every one of the 68 existing tests asked only "does this check fire". None asked "does it stay silent when it should", which is precisely the hole `auth-2` fell through. Borrowed from KICS, which refuses a rule that ships without a negative fixture, and from Checkov, which requires both a passing and a failing case. `auth-2` now has four silence tests: middleware-protected, signature-verified, shared-secret, and correctly-fired.
+
+Tests: 86.
+
 ## 3.5.0
 
 3.4.0 made the engine honest about what it found. This release is about what it was never looking at, and about the toolkit holding together as one thing.

README.md

@@ -86,7 +86,7 @@ It reads files, so it can tell you a control is missing or that a guard lets eve
 
 Both ask "is it ready?" They answer different halves.
 
-- **`prod-readiness-coach`** runs a script. Same repo, same findings every time. It checks the plumbing: automatic tests, error alerts, secrets, undo plans, and whether a rollback on one platform leaves another out of sync. Run it first, the day you go live, and again before any launch.
+- **`prod-readiness-coach`** runs a script. Same repo, same findings every time. It checks the plumbing: automatic tests, error alerts, secrets, undo plans, and whether a rollback on one platform leaves another out of sync. The checks that read your repository work in any language. The checks that need to know your stack are strongest on Node and Next.js, good on Python, and tell you plainly when they have no rules for your language instead of guessing. Run it first, the day you go live, and again before any launch.
 - **`product-readiness-review`** is Claude's judgment. Does the product do what it says? What would break first for a real person? Run it after the coach, when the plumbing is in.
 
 ## What CI is, if nobody ever told you

docs/decisions/006-auth-2-middleware-and-signatures.md

@@ -0,0 +1,19 @@
+# 006: `auth-2` reports middleware as something to confirm, not as a failure
+
+**Decision.** `auth-2` no longer calls a request handler unguarded just because the word "auth" is missing from the file. It now recognizes three ways a handler can be authenticated, and when it finds request middleware, it drops from a HIGH failure to a LOW warning that names the middleware and lists its public route patterns.
+
+**Why this came up.** On a live application, `auth-2` reported "18 of 25 request handlers never mention an auth check" as a HIGH finding. Reading the flagged files, at least 14 of them were authenticated. Three mechanisms the check could not see: middleware that guards every route not on a public list, webhook routes that verify a cryptographic signature because a machine is calling and cannot carry a browser session, and routes that compare a shared secret from the environment. What was at stake: a HIGH finding that is wrong about half the time is worse than no finding, because it teaches people to scroll past the real ones. The same report contained a genuine critical finding, `auth-3`, sitting underneath eighteen false ones.
+
+**Options.**
+1. Delete `auth-2` until it can be right. Cost: a genuinely unguarded handler, which is the most common way a small app leaks data, goes unreported entirely.
+2. Teach it the three mechanisms and keep the HIGH severity. Cost: a file scan still cannot prove a middleware route pattern covers a given path, because those patterns are globs evaluated when a request arrives. The check would still be asserting something it cannot know.
+3. Teach it the three mechanisms, and when middleware exists, change what the finding claims: not "these are unguarded" but "these rely on middleware, confirm the matcher covers them". Drop the severity, and print the public patterns so a person can check in about a minute. Cost: a route that middleware genuinely misses is now a LOW warning rather than a HIGH failure, and a hurried reader may skip it.
+
+**What we chose and why.** Option 3. Joint call: the handoff leaned this way and Claude implemented it. The deciding argument is the toolkit's own rule, that a tool must never claim more than it checked. The tool checked that middleware exists. It did not check that the matcher covers these paths. So that is exactly what the finding should say. The severity follows the certainty, not the topic.
+
+**What we gave up.** Loudness on a real class of bug. If someone adds a route that their middleware matcher happens to exclude, this now arrives as a LOW warning in a list, not a HIGH finding at the top. We accepted that because the alternative was eighteen false HIGH findings burying one true CRITICAL.
+
+**How we'll know if this was right.** On the live test application the finding goes from 18 flagged to 9, and each of the 9 is genuinely middleware-dependent rather than authenticated some other way. Longer term: nobody reports a handler that this warning mentioned and they dismissed, which turned out to be open.
+
+**What actually happened.**
+(Tarik fills this in.)

docs/decisions/007-supported-languages.md

@@ -0,0 +1,19 @@
+# 007: Node and Next.js and Python are supported. Everything else gets the checks that do not care.
+
+**Decision.** The tool no longer claims to work on any repository regardless of language. Checks split into two kinds. Checks that read the repository itself, is there CI, does it gate pull requests, is `.env` ignored, is there a runbook with real words in it, run on anything. Checks that need to understand the stack are supported on Node, Next.js and Python only, and on any other language they say what they could not check instead of guessing.
+
+**Why this came up.** Five separate bugs turned out to be one bug wearing different hats: the engine only really knew Node. A helper returned a fake empty `package.json`, which is truthy in Python, so a Go repository was told "package.json exists but does not define a test script" about a file that was not there. The lint-step check knew `eslint` and `ruff` but not `mypy` or `golangci-lint`. The health-endpoint check could only find a route that was a file path, which is how Next.js declares one and how no other framework does. Sixty-eight tests caught none of it, because every fixture in the suite was a JavaScript repository. What was at stake: the tool's entire value is that it does not overstate what it looked at, and the sentence "it works on any git repo regardless of language/framework" was the tool overstating where it looked.
+
+**Options.**
+1. Keep the "any language" claim and keep patching. Cost: every new language is an edit in five files, the claim stays false in between, and the tool earns a reputation for lying about ecosystems it never supported.
+2. Support Node, Next.js, Python and Go properly. Cost: Go is a fourth surface to keep correct, and Go is not who this tool is for. Its audience is self-taught developers shipping AI-assisted apps, which in practice means Next.js and Python.
+3. Support Node, Next.js and Python. Split the checks so the language-agnostic ones still run everywhere, and make "no rules for Go" an explicit, named outcome that is left out of the score rather than counted as a failure.
+
+**What we chose and why.** Option 3. Tarik's call, after research into how seven mature audit tools handle the same problem. OpenSSF Scorecard has a third outcome besides pass and fail, an inconclusive result scored `-1`, used when a check does not apply or the repository's language is unsupported, and it is excluded from the aggregate rather than penalized. Checkov has the same idea under the name `UNKNOWN`. That is the honest shape, and this codebase already had the machinery: an `n/a` status that is dropped from scoring.
+
+**What we gave up.** The broad claim, which was the more impressive-sounding one. A Go or Ruby user now gets a smaller report. That is the correct trade: a smaller true report beats a larger one with invented findings in it.
+
+**How we'll know if this was right.** A Go repository's report contains no statement about a file that does not exist, and names what it skipped. Adding a language later is one PR that adds an applicability tag and a fixture pair, not an edit across five files.
+
+**What actually happened.**
+(Tarik fills this in.)

skills/prod-readiness-coach/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prod-readiness-coach
-description: "Audits any code repository for production-readiness gaps (CI/CD pipeline, structured logging, error tracking, secrets management, CLAUDE.md/AGENTS.md, resilience/runbooks, multi-surface deployment and coordinated rollback risk, irreversible migrations, test coverage, dependency security) and produces two plain-English documents: a beginner-friendly audit explainer and a phase-gated Claude Code fix brief. Detects the repo's stack (frameworks, deploy platforms, runtimes) and loads matching stack-specific reference material so advice reflects real platform gotchas instead of generic checklist language. Use when a user asks to audit, check, or review a repo for production readiness, best practices, or launch-blockers, or asks to turn code-quality/DevOps findings into something a non-expert or self-taught (\"vibe coder\") developer can understand and act on. Use for repository controls and static scanning; run it first on broad production-readiness requests. Do not use alone to judge user journeys or product correctness; that is product-readiness-review."
+description: "Scans repository controls and scripts, not user journeys: access control on request handlers, CI/CD pipeline, structured logging, error tracking, secrets management, CLAUDE.md/AGENTS.md, resilience and runbooks, multi-surface deployment and coordinated rollback risk, irreversible migrations, test coverage, and dependency security. Runs a deterministic script, then produces two plain-English documents: a beginner-friendly audit explainer and a phase-gated Claude Code fix brief. Detects the repo's stack (frameworks, deploy platforms, runtimes) and loads matching stack-specific reference material so advice reflects real platform gotchas instead of generic checklist language. Repository-level checks run on any language; stack-specific checks are strongest on Node and Next.js, good on Python, and report what they could not check elsewhere. Use when a user asks to audit, check, or review a repo for production readiness, best practices, or launch-blockers, or asks to turn code-quality/DevOps findings into something a non-expert or self-taught (\"vibe coder\") developer can understand and act on. Run it first on broad production-readiness requests. Do not use it alone to judge user journeys or product correctness; that is product-readiness-review."
 ---
 
 # Production Readiness Coach
@@ -348,9 +348,32 @@ with no documented reverse procedure), that last check runs for every
 repo regardless of surface count, since a single-surface app can still
 lose data permanently to a migration that a code rollback can't undo.
 
-It works on any git repo regardless of language/framework, repos with no
-recognized deploy platform still get a clean fingerprint (empty surfaces,
-`multi_surface: false`) rather than a crash. See its own `--help` output
+Language coverage is not even, and the report has to say so. Checks that
+read the repository itself work on anything: is there CI, does it run on
+pull requests, is `.env` ignored, is there a runbook with real words in it,
+are there secrets in the code, is there a CLAUDE.md. Checks that need to
+know the stack are narrower. They are strongest on Node and Next.js, good
+on Python, and have no rules for Go, Rust, Ruby, Java, PHP or C#.
+
+On a language with no rules, this is what that looks like:
+
+- `ci-6` (a test command in the manifest) reads a `test` script in
+  package.json and a pytest configuration, nothing else. On a Go or Rust
+  repo it reports "no test entry point found" and names the two things it
+  read, so the reader can see the gap is in the tool.
+- `auth-1` looks for an authentication package in package.json,
+  requirements.txt or pyproject.toml. A Go or Ruby auth library is invisible
+  to it.
+- `auth-2` finds request handlers by Next.js, Express and FastAPI path
+  shapes. A chi router or a Rails controller is never scanned.
+- When no framework is recognized, the profile is "unknown" and every
+  runtime check reports n/a with "insufficient evidence" rather than
+  failing. Pass `--profile api` to run them anyway.
+
+It never crashes on an unfamiliar repo, and it never invents a finding
+about a file that is not there. Repos with no recognized deploy platform
+still get a clean fingerprint (empty surfaces, `multi_surface: false`).
+What it did not check, it says it did not check. See its own `--help` output
 for CLI flags; the ones that matter here are `--json` (for this skill's
 translation step), `--context` (for the product-context calibration in
 step 1, stored verbatim, never alters the score), and `--fail-on