stopslop 1.1.0 → 1.2.1

package/COMPATIBILITY.md

@@ -1,6 +1,6 @@
 # Compatibility
 
-Last updated: 1.1.0
+Last updated: 1.2.1 (2026-11-02)
 
 StopSlop follows Semantic Versioning. Stable surfaces change incompatibly only
 in a major release. Experimental surfaces may change in a minor release; such
@@ -13,12 +13,17 @@ changes are called out in the changelog.
 | SARIF 2.1.0 report | Stable | New rules and optional properties may be added; existing required fields remain compatible. |
 | `stopslop.json` schema | Stable | New settings may be added; configuration valid in a 1.x release stays valid in every later 1.x release. |
 | Programmatic Node.js API | Experimental | Exported functions and TypeScript types may change in a minor release. |
+| Agent plugins (`stopslop` skill and stop hook for Claude Code, Codex, Cursor, Gemini CLI) | Experimental | When the hook runs, what it reports, and the skill's instructions may change in a minor release. |
 
 Findings and scores are not a compatibility surface. Detector fixes, threshold
 calibration, and Knip or Clone Alert updates can change what a release reports
 for the same code; such changes are called out in the changelog. Pin the
 StopSlop version in CI when a gate must not move without a commit.
 
+Version 1.2.1 preserves all stable surfaces and adds no deprecations. Anonymous
+function detection and analysis-engine updates can produce new findings or
+different scores for existing code.
+
 ## Runtime support
 
 - Node.js 20.19+, 22.12+, and 24.

package/README.md

@@ -42,6 +42,41 @@ uses [Clone Alert](https://www.npmjs.com/package/clone-alert); dead-code analysi
 uses [Knip](https://knip.dev). StopSlop detects code patterns, not whether a human
 or an AI wrote them.
 
+## A passing test does not mean the feature is connected
+
+An agent adds a discount function and a test:
+
+```ts
+// src/discount.ts
+export function applyDiscount(total: number): number {
+  return total * 0.9;
+}
+```
+
+```ts
+// test/discount.test.ts
+import { strictEqual } from 'node:assert';
+import { test } from 'node:test';
+import { applyDiscount } from '../src/discount.js';
+
+test('applies a 10% discount', () => {
+  strictEqual(applyDiscount(100), 90);
+});
+```
+
+The test passes, but checkout still calculates the total without calling
+`applyDiscount`. StopSlop reports:
+
+```text
+  1 orphan feature
+
+   orphan feature  `applyDiscount` is only used by the test `test/discount.test.ts`; connect it to production code, or remove it and its test if unneeded
+      src/discount.ts:1
+```
+
+If the discount belongs in checkout, connect it and keep the test. If the feature
+was abandoned, remove the unused function and its test.
+
 ## Start with one command
 
 Run without installing:
@@ -177,18 +212,54 @@ For GitHub Code Scanning, emit SARIF before propagating the gate failure:
 npx stopslop . --base origin/main --format sarif > stopslop.sarif
 ```
 
+Every rule in the SARIF report carries its help, so the alert says why the
+finding matters and how to fix it, not only what failed.
+
 See [CI and automation](docs/ci-and-automation.md) for a complete workflow that
 uploads SARIF and still preserves StopSlop's exit code.
 
-## Send the findings back to the agent
-
-The JSON report is stable and versioned. Feed it into the next coding-agent turn
-instead of paraphrasing terminal output:
+## Catch slop while the agent is still working
+
+A check that first runs on the pull request reports code nobody remembers
+writing. StopSlop can run inside the coding session instead, while the code is
+still in front of the agent.
+
+This repository is a plugin for Claude Code, Codex, and Cursor and an extension
+for Gemini CLI. Each agent gets the `stopslop` skill, which covers how to run the
+check, read the report, and fix each kind of finding without gaming it: no
+raised thresholds, no ignore globs, no baseline edits on the agent's own
+initiative. Where the agent supports it, the install also adds a stop hook.
+
+| Agent | Install | Stop hook |
+| --- | --- | --- |
+| Claude Code | `/plugin marketplace add BaryshevRS/stopslop`<br>`/plugin install stopslop@stopslop` | included |
+| Codex | `codex plugin marketplace add BaryshevRS/stopslop`<br>`codex plugin add stopslop@stopslop` | included; trust it when Codex asks at session start |
+| Cursor | Customize → import `BaryshevRS/stopslop` from a GitHub repository | included |
+| Gemini CLI | `gemini extensions install https://github.com/BaryshevRS/stopslop` | [in project settings](docs/ci-and-automation.md#commit-the-hook-to-the-project) |
+| Others | `npx skills add BaryshevRS/stopslop` (skill only) | — |
+
+Before the agent ends a turn that changed JS/TS source, the hook checks the
+uncommitted changes against `HEAD`, or against `.stopslop-baseline.json` when
+the project has one, and hands any new findings back with how to fix each kind.
+Legacy never blocks a turn, a turn that changed no source costs one
+`git status`, and the agent gets one nudge per turn: accepting a finding stays
+your decision. The hook runs the project's pinned `stopslop` from `node_modules`
+and falls back to `npx stopslop@1`.
+
+The hook also ships in the npm package, so a project that pins `stopslop` can
+commit it to its own agent settings and give it to every contributor; see
+[Commit the hook to the project](docs/ci-and-automation.md#commit-the-hook-to-the-project).
+
+**Any agent or script.** The JSON report is stable and versioned. Feed it into
+the next turn instead of paraphrasing terminal output:
 
 ```bash
-npx stopslop . --json > slop-report.json
+npx stopslop . --base HEAD --json > slop-report.json
 ```
 
+Each finding carries `kind`, `file`, `line`, and `message`, and `rules` says for
+each reported kind why it matters and what resolves it: the same text as
+[docs/rules.md](docs/rules.md) and the rule help in GitHub Code Scanning.
 God-unit findings include member groups that serve as concrete refactoring
 boundaries. Clone findings include every occurrence. Baseline and Git-base runs
 retain the complete score while returning only new findings.
@@ -308,8 +379,9 @@ is experimental and may change in a minor release; see
 - A baseline accepts finding identities. If an accepted function becomes more
   complex without changing identity, the score rises but the gate stays clear.
 
-Architecture, research references, and the boundary between published methods
-and StopSlop heuristics are documented in [ARCH.md](ARCH.md).
+The score formula and its limits are in [docs/score.md](docs/score.md), how
+the default thresholds were calibrated in [docs/thresholds.md](docs/thresholds.md),
+and what each finding means in [docs/rules.md](docs/rules.md).
 
 ## FAQ
 

package/context7.json

@@ -17,6 +17,8 @@
     "Use `--fast` only when intentionally skipping duplicate-code and dead-code analysis; it runs the AST checks for cognitive complexity and god units.",
     "The Node API is ESM and typed: call `resolveConfig()` before `analyze()`, or call `loadConfig()` to read stopslop.json. The slop score always describes the complete analyzed repository.",
     "Clone detection is powered by Clone Alert and dead-code analysis by Knip. Configure Knip only under the `knip` property in stopslop.json.",
-    "Knip settings go under `knip` in stopslop.json; a project's own knip.json or package.json#knip is never read. Do not write one up front — run the analysis and follow the `config hints` it prints, which come from Knip and name what is missing."
+    "Knip settings go under `knip` in stopslop.json; a project's own knip.json or package.json#knip is never read. Do not write one up front — run the analysis and follow the `config hints` it prints, which come from Knip and name what is missing.",
+    "Every reported kind has help: the JSON report's `rules` block and SARIF rule help give `why` and `fix`, the same text as docs/rules.md. Fix the code; do not raise thresholds or edit the baseline to get a clear run.",
+    "The repo is a plugin for Claude Code, Codex and Cursor and a Gemini CLI extension: a stopslop skill plus a stop hook reporting findings the uncommitted changes added. Other agents: `npx skills add BaryshevRS/stopslop`."
   ]
 }

package/dist/cli.js

@@ -162,6 +162,85 @@ function countByKind(findings) {
 	for (const f of findings) counts[f.kind]++;
 	return counts;
 }
+//#endregion
+//#region src/report/rules.ts
+const RULES_DOC = "https://github.com/BaryshevRS/stopslop/blob/main/docs/rules.md";
+const RULES = {
+	"cognitive-complexity": {
+		summary: "Function is harder to follow than the threshold allows",
+		why: "Cognitive complexity counts what a reader has to hold in mind to follow a function: branches, loops, nesting, and boolean chains (SonarSource specification). Above the threshold a function is hard to review and easy to break, and it keeps growing the same way: each new case lands beside the existing ones instead of in a place of its own.",
+		fix: "Return early instead of nesting, and move each independent decision into a function whose name says what it decides. Replace a long if/else or switch over one value with a lookup table. Cutting the body into arbitrary part1/part2 helpers moves the complexity without removing it.",
+		config: "cognitiveComplexity"
+	},
+	"god-module": {
+		summary: "Module mixes unrelated responsibilities or has outgrown one file",
+		why: "Its top-level definitions fall into groups that do not use each other, or the file is too large and too complex to be one unit. Every change touches a file that does several jobs, and new code keeps landing in it because it is the file already open.",
+		fix: "Move each responsibility group to its own module; `--details` and the JSON report list the groups found in the reference graph, the ready-made split boundaries. Members listed as holding cohesion together are shared helpers: move them where every group can import them. A size-axis finding has no clean boundaries, so split it by responsibility by hand.",
+		config: "godModule"
+	},
+	"god-class": {
+		summary: "Class mixes unrelated responsibilities or has outgrown one unit",
+		why: "Its methods fall into groups that do not share state or call each other, or the class is too large and too complex to be one unit. Every change risks the unrelated behaviour next to it, and the class cannot be tested one responsibility at a time.",
+		fix: "Extract each responsibility group into its own class or set of functions, and let the original delegate to them or disappear; `--details` and the JSON report list the groups. A size-axis finding has no clean boundaries, so split it by responsibility by hand.",
+		config: "godClass"
+	},
+	"multiple-exported-classes": {
+		summary: "File exports more than one class",
+		why: "Several exported classes in one file usually mean code was appended where it was convenient instead of placed where it belongs. Readers cannot find a class by its file name, and the file drifts toward a god module.",
+		fix: "Give each exported class its own file named after it. A class that only serves another can stay in the same file without being exported.",
+		config: "multipleExportedClasses"
+	},
+	"duplicate-code": {
+		summary: "Block of code is copied in more than one place",
+		why: "Copies drift. A bug fixed in one stays in the others, and the copies start to disagree about the same computation. It is usually cheaper to write a block again than to find the helper that already does it, which is how copies accumulate.",
+		fix: "Extract the block into one function and call it from every occurrence; the finding lists all of them. Where the copies differ on purpose, make the difference a parameter. Renaming variables does not hide a copy when `duplicates.ignoreIdentifiers` is on.",
+		config: "duplicates"
+	},
+	"unused-export": {
+		summary: "Export is not imported anywhere",
+		why: "Code nothing uses still has to be read, compiled, kept type-correct, and migrated. Code is added readily and deleted reluctantly, so unused exports only accumulate.",
+		fix: "Delete it, or drop the `export` keyword when the file uses it internally. If something Knip does not know about uses it, such as a framework convention or a public package entry, declare that entry under `knip` in stopslop.json instead.",
+		config: "deadCode.exports"
+	},
+	"unused-dependency": {
+		summary: "Dependency in package.json is not imported anywhere",
+		why: "An unused package still installs, still gets audited and updated, and still widens the supply chain the project trusts.",
+		fix: "Remove it from package.json. If it is used in a way Knip cannot see, such as a binary run from a script or a plugin loaded by name, list it in `ignoreDependencies` under `knip` in stopslop.json.",
+		config: "deadCode.dependencies"
+	},
+	"unused-file": {
+		summary: "File is not reachable from any entry point",
+		why: "Often a superseded version of a module, left next to the one that replaced it. Reported as info and not scored: the result is only as good as the entry points Knip knows.",
+		fix: "Resolve the config hints in the report first; a missing entry point makes live files look unreachable. Then delete the file.",
+		config: "deadCode.files"
+	},
+	"orphan-feature": {
+		summary: "Function or class is used only by its own test",
+		why: "No production code calls it; one test is the only thing that imports it. This can be a feature written together with its test and never wired in, and the green test makes it look finished.",
+		fix: "Check whether the feature is meant to exist. If so, wire it into the production code that needs it. Otherwise, remove the unused symbol and its test together: deleting only the source breaks the test, and deleting only the test leaves dead code.",
+		config: "deadCode.orphans"
+	}
+};
+function ruleHelp(kind) {
+	return {
+		...RULES[kind],
+		helpUri: `${RULES_DOC}#${kind}`
+	};
+}
+/** Help for the kinds present in a set of findings, keyed by kind. */
+function rulesFor(findings) {
+	const rules = {};
+	for (const { kind } of findings) rules[kind] ??= ruleHelp(kind);
+	return rules;
+}
+/** The rule's help as Markdown: the body of a SARIF rule help and of docs/rules.md. */
+function ruleMarkdown(rule) {
+	return [
+		`**Why it matters.** ${rule.why}`,
+		`**How to fix.** ${rule.fix}`,
+		`**Tune or disable:** \`${rule.config}\` in \`stopslop.json\`.`
+	].join("\n\n");
+}
 const KINDS = [
 	"god-module",
 	"god-class",
@@ -209,6 +288,7 @@ function toJson(result) {
 		},
 		summary: summarize(result),
 		findings: result.findings,
+		rules: rulesFor(result.findings),
 		notes: result.notes,
 		configHints: result.configHints,
 		/** Where Knip settings are read from. Nowhere else is consulted. */
@@ -233,9 +313,17 @@ function toSarif(result) {
 	for (const finding of result.findings) {
 		if (seenRules.has(finding.kind)) continue;
 		seenRules.add(finding.kind);
+		const rule = ruleHelp(finding.kind);
 		rules.push({
 			id: finding.kind,
-			shortDescription: { text: describeKind(finding.kind) },
+			name: ruleName(finding.kind),
+			shortDescription: { text: rule.summary },
+			fullDescription: { text: rule.why },
+			help: {
+				text: `${rule.why}\n\n${rule.fix}\n\nTune or disable: ${rule.config} in stopslop.json.`,
+				markdown: ruleMarkdown(rule)
+			},
+			helpUri: rule.helpUri,
 			defaultConfiguration: { level: sarifLevel(finding.severity) }
 		});
 	}
@@ -261,9 +349,9 @@ function toSarif(result) {
 function sarifLevel(severity) {
 	return severity === "warn" ? "warning" : "note";
 }
-function describeKind(kind) {
-	const description = kind.replaceAll("-", " ");
-	return `${description.charAt(0).toUpperCase()}${description.slice(1)}`;
+/** SARIF rule name, the identifier Code Scanning filters by: `god-class` → `GodClass`. */
+function ruleName(kind) {
+	return kind.split("-").map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1)}`).join("");
 }
 function locationsFor(root, finding) {
 	const primaryUri = artifactUri(root, finding.file);

package/docs/ci-and-automation.md

@@ -83,7 +83,121 @@ npx stopslop . --format json > slop-report.json
 The JSON schema version is included in the document. Findings carry stable
 `kind`, `file`, `symbol`, `line`, `message`, and optional structured `data`
 fields. God-unit data includes responsibility groups; duplicate-code data
-includes clone locations.
+includes clone locations. `rules` holds, for each reported kind, its `summary`,
+`why`, `fix`, the `config` setting that tunes it, and a `helpUri` into
+[rules.md](rules.md), so the agent does not have to guess what a rule wants.
+
+## Run the check inside the agent session
+
+The repository is a plugin for Claude Code, Codex, and Cursor and an extension
+for Gemini CLI; the [README](../README.md#catch-slop-while-the-agent-is-still-working)
+lists the install command for each. All of them get the `stopslop` skill. The
+stop hook, `hooks/stop-gate.mjs`, runs when the agent is about to end a turn. It
+asks Git whether any JS/TS source or `package.json` changed, and if something
+did, it runs
+
+```bash
+npx stopslop . --baseline .stopslop-baseline.json --format json  # when the file exists
+npx stopslop . --base HEAD --format json                         # otherwise
+```
+
+and hands the new findings back to the agent with each kind's fix, which the
+agent receives as its next instruction. It does not block on analysis errors,
+and it nudges once per turn, so a finding you decide to keep cannot loop the
+session. It runs the project's own `node_modules/stopslop` when installed,
+otherwise `npx stopslop@1`.
+
+| Agent | Hook event | Hook answer |
+| --- | --- | --- |
+| Claude Code, Codex | `Stop` | `decision: "block"` with the findings as `reason` |
+| Gemini CLI | `AfterAgent` | the same |
+| Cursor | `stop` (`--agent cursor`) | `followup_message` |
+
+Codex runs plugin hooks only after you trust them; it asks at the start of the
+first session after install.
+
+## Commit the hook to the project
+
+`hooks/stop-gate.mjs` ships in the npm package. A project that pins `stopslop`
+in `devDependencies` can commit the hook to its agent settings, so every
+contributor gets it without installing a plugin. This is also the way to the
+hook for Gemini CLI: an extension reads hooks only from `hooks/hooks.json`,
+which in this repository holds the Claude Code and Codex hook.
+
+Gemini CLI, `.gemini/settings.json`:
+
+```json
+{
+  "hooks": {
+    "AfterAgent": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$GEMINI_PROJECT_DIR/node_modules/stopslop/hooks/stop-gate.mjs\"",
+            "timeout": 300000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Claude Code, `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/node_modules/stopslop/hooks/stop-gate.mjs\"",
+            "timeout": 300
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Codex, `.codex/hooks.json`; Codex runs the hook in the session's working
+directory:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node node_modules/stopslop/hooks/stop-gate.mjs",
+            "timeout": 300
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Cursor, `.cursor/hooks.json`; project hooks run from the project root:
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "stop": [{ "command": "node node_modules/stopslop/hooks/stop-gate.mjs --agent cursor" }]
+  }
+}
+```
+
+Agents without a plugin system or hooks get the skill alone with
+`npx skills add BaryshevRS/stopslop`.
 
 ## Generate a binary Shields badge
 

package/docs/configuration.md

@@ -62,7 +62,8 @@ the corpus it sits between count p95 ≈ 13 and p99 ≈ 38). Lower = stricter.
 ### `godClass` / `godModule` — object | false
 
 A class (or a module's top-level definitions) is flagged on **either** of two
-axes — see [ARCH.md](../ARCH.md) for the reasoning.
+axes, described below; [thresholds.md](thresholds.md) has the calibration behind
+the defaults.
 
 | field | meaning | default (class / module) |
 |---|---|---|

package/docs/rules.md

@@ -0,0 +1,102 @@
+<!-- Generated from src/report/rules.ts by `pnpm rules:generate`. Do not edit by hand. -->
+
+# Rules
+
+Every StopSlop finding has a `kind`. This page says, for each one, why it is a
+finding and what resolves it. The same text is the rule help in GitHub Code
+Scanning (`--format sarif`) and the `rules` block of `--format json`, so a
+reviewer and a coding agent read the same instructions.
+
+Every setting named below lives in `stopslop.json`; see the
+[configuration reference](configuration.md). Setting a check to `false`
+disables it.
+
+## cognitive-complexity
+
+Function is harder to follow than the threshold allows.
+
+**Why it matters.** Cognitive complexity counts what a reader has to hold in mind to follow a function: branches, loops, nesting, and boolean chains (SonarSource specification). Above the threshold a function is hard to review and easy to break, and it keeps growing the same way: each new case lands beside the existing ones instead of in a place of its own.
+
+**How to fix.** Return early instead of nesting, and move each independent decision into a function whose name says what it decides. Replace a long if/else or switch over one value with a lookup table. Cutting the body into arbitrary part1/part2 helpers moves the complexity without removing it.
+
+**Tune or disable:** `cognitiveComplexity` in `stopslop.json`.
+
+## god-module
+
+Module mixes unrelated responsibilities or has outgrown one file.
+
+**Why it matters.** Its top-level definitions fall into groups that do not use each other, or the file is too large and too complex to be one unit. Every change touches a file that does several jobs, and new code keeps landing in it because it is the file already open.
+
+**How to fix.** Move each responsibility group to its own module; `--details` and the JSON report list the groups found in the reference graph, the ready-made split boundaries. Members listed as holding cohesion together are shared helpers: move them where every group can import them. A size-axis finding has no clean boundaries, so split it by responsibility by hand.
+
+**Tune or disable:** `godModule` in `stopslop.json`.
+
+## god-class
+
+Class mixes unrelated responsibilities or has outgrown one unit.
+
+**Why it matters.** Its methods fall into groups that do not share state or call each other, or the class is too large and too complex to be one unit. Every change risks the unrelated behaviour next to it, and the class cannot be tested one responsibility at a time.
+
+**How to fix.** Extract each responsibility group into its own class or set of functions, and let the original delegate to them or disappear; `--details` and the JSON report list the groups. A size-axis finding has no clean boundaries, so split it by responsibility by hand.
+
+**Tune or disable:** `godClass` in `stopslop.json`.
+
+## multiple-exported-classes
+
+File exports more than one class.
+
+**Why it matters.** Several exported classes in one file usually mean code was appended where it was convenient instead of placed where it belongs. Readers cannot find a class by its file name, and the file drifts toward a god module.
+
+**How to fix.** Give each exported class its own file named after it. A class that only serves another can stay in the same file without being exported.
+
+**Tune or disable:** `multipleExportedClasses` in `stopslop.json`.
+
+## duplicate-code
+
+Block of code is copied in more than one place.
+
+**Why it matters.** Copies drift. A bug fixed in one stays in the others, and the copies start to disagree about the same computation. It is usually cheaper to write a block again than to find the helper that already does it, which is how copies accumulate.
+
+**How to fix.** Extract the block into one function and call it from every occurrence; the finding lists all of them. Where the copies differ on purpose, make the difference a parameter. Renaming variables does not hide a copy when `duplicates.ignoreIdentifiers` is on.
+
+**Tune or disable:** `duplicates` in `stopslop.json`.
+
+## unused-export
+
+Export is not imported anywhere.
+
+**Why it matters.** Code nothing uses still has to be read, compiled, kept type-correct, and migrated. Code is added readily and deleted reluctantly, so unused exports only accumulate.
+
+**How to fix.** Delete it, or drop the `export` keyword when the file uses it internally. If something Knip does not know about uses it, such as a framework convention or a public package entry, declare that entry under `knip` in stopslop.json instead.
+
+**Tune or disable:** `deadCode.exports` in `stopslop.json`.
+
+## unused-dependency
+
+Dependency in package.json is not imported anywhere.
+
+**Why it matters.** An unused package still installs, still gets audited and updated, and still widens the supply chain the project trusts.
+
+**How to fix.** Remove it from package.json. If it is used in a way Knip cannot see, such as a binary run from a script or a plugin loaded by name, list it in `ignoreDependencies` under `knip` in stopslop.json.
+
+**Tune or disable:** `deadCode.dependencies` in `stopslop.json`.
+
+## unused-file
+
+File is not reachable from any entry point.
+
+**Why it matters.** Often a superseded version of a module, left next to the one that replaced it. Reported as info and not scored: the result is only as good as the entry points Knip knows.
+
+**How to fix.** Resolve the config hints in the report first; a missing entry point makes live files look unreachable. Then delete the file.
+
+**Tune or disable:** `deadCode.files` in `stopslop.json`.
+
+## orphan-feature
+
+Function or class is used only by its own test.
+
+**Why it matters.** No production code calls it; one test is the only thing that imports it. This can be a feature written together with its test and never wired in, and the green test makes it look finished.
+
+**How to fix.** Check whether the feature is meant to exist. If so, wire it into the production code that needs it. Otherwise, remove the unused symbol and its test together: deleting only the source breaks the test, and deleting only the test leaves dead code.
+
+**Tune or disable:** `deadCode.orphans` in `stopslop.json`.

package/hooks/stop-gate.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// Coding-agent hook, run when the agent is about to end its turn. Check whether
+// the uncommitted changes added slop, and if they did, hand the findings back
+// while the code is still in front of the agent rather than in a review later.
+//
+// It reports only what the changes added — findings absent from
+// .stopslop-baseline.json when the project gates on one, otherwise absent from
+// HEAD — so legacy never blocks a turn. Turns that changed no JS/TS source cost
+// one `git status`. Analysis errors never block: the gate is CI's job, this
+// hook is feedback.
+//
+//   node stop-gate.mjs                  Claude Code (Stop), Codex (Stop), Gemini CLI (AfterAgent)
+//   node stop-gate.mjs --agent cursor   Cursor (stop)
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const BASELINE = '.stopslop-baseline.json';
+const RULES_DOC = 'https://github.com/BaryshevRS/stopslop/blob/main/docs/rules.md';
+const SOURCE = /\.[cm]?[jt]sx?$|(?:^|\/)package\.json$/;
+/** Findings listed in full; the rest are counted. Keeps the feedback short. */
+const MAX_LISTED = 20;
+
+/** How each agent hands the hook its turn and takes the feedback back. */
+const AGENTS = {
+  // Claude Code, Codex, and Gemini CLI share one protocol: the project in `cwd`,
+  // a flag set once a hook already sent the agent back, and a block decision
+  // whose reason the agent receives as its next instruction. Codex rejects any
+  // other output field, so this is the whole answer.
+  default: {
+    root: (input) => input.cwd || process.cwd(),
+    resumed: (input) => input.stop_hook_active === true,
+    answer: (feedback) => ({ decision: 'block', reason: feedback }),
+  },
+  // Cursor runs plugin hooks from the plugin directory and names the project in
+  // the environment. Only a turn that completed is checked: an aborted one was
+  // the user's call, a failed one has nothing finished to review.
+  cursor: {
+    root: (input) => process.env.CURSOR_PROJECT_DIR ?? input.workspace_roots?.[0],
+    resumed: (input) => input.status !== 'completed' || input.loop_count > 0,
+    answer: (feedback) => ({ followup_message: feedback }),
+  },
+};
+
+/** The feedback for the agent, or undefined to let it end the turn. */
+function gate(root) {
+  if (!changesSource(root)) return undefined;
+
+  const mode = existsSync(join(root, BASELINE))
+    ? { args: ['--baseline', BASELINE], what: `not in ${BASELINE}` }
+    : { args: ['--base', 'HEAD'], what: 'added by the uncommitted changes' };
+  const { status, stdout } = runStopslop(root, ['.', ...mode.args, '--format', 'json']);
+  if (status !== 1) return undefined;
+
+  let report;
+  try {
+    report = JSON.parse(stdout);
+  } catch {
+    return undefined;
+  }
+  if (!Array.isArray(report.findings) || report.findings.length === 0) return undefined;
+  return feedback(report, mode);
+}
+
+/** True when Git shows a changed or new JS/TS source file or package.json. */
+function changesSource(root) {
+  const status = spawnSync('git', ['status', '--porcelain', '-z', '--untracked-files=all'], {
+    cwd: root,
+    encoding: 'utf8',
+  });
+  if (status.status !== 0) return false; // not a Git work tree: nothing to compare with
+  // Each entry is "XY path"; a rename adds its old path as the next entry. Only
+  // the extension matters, so the status prefix needs no parsing.
+  return status.stdout.split('\0').some((entry) => SOURCE.test(entry));
+}
+
+function runStopslop(root, args) {
+  // The project's own pinned version first — the one its CI runs.
+  const local = join(root, 'node_modules', 'stopslop', 'dist', 'cli.js');
+  const [command, prefix] = existsSync(local)
+    ? [process.execPath, [local]]
+    : ['npx', ['--yes', 'stopslop@1']];
+  const result = spawnSync(command, [...prefix, ...args], {
+    cwd: root,
+    encoding: 'utf8',
+    env: { ...process.env, NO_COLOR: '1' },
+    maxBuffer: 64 * 1024 * 1024,
+    shell: command === 'npx' && process.platform === 'win32',
+    timeout: 280_000,
+  });
+  return { status: result.status, stdout: result.stdout ?? '' };
+}
+
+function feedback(report, mode) {
+  const { findings } = report;
+  const rules = report.rules ?? {};
+  const command = `npx stopslop . ${mode.args.join(' ')}`;
+  const lines = [`StopSlop: ${plural(findings.length, 'finding')} ${mode.what} (\`${command}\`).`];
+
+  const byKind = new Map();
+  for (const finding of findings.slice(0, MAX_LISTED)) {
+    if (!byKind.has(finding.kind)) byKind.set(finding.kind, []);
+    byKind.get(finding.kind).push(finding);
+  }
+  for (const [kind, group] of byKind) {
+    const rule = rules[kind];
+    lines.push('', rule ? `${kind} — ${rule.summary}` : kind);
+    for (const finding of group) {
+      lines.push(`  ${finding.file}:${finding.line}  ${finding.message}${alsoAt(finding)}`);
+    }
+    if (rule) lines.push(`  How to fix: ${rule.fix}`);
+  }
+  if (findings.length > MAX_LISTED) {
+    lines.push('', `${findings.length - MAX_LISTED} more not listed; \`${command} --json\` has all.`);
+  }
+
+  lines.push(
+    '',
+    'Fix these before ending the turn. If one should stay, tell the user which and why: ' +
+      `accepting it into the reviewed ${BASELINE} is their decision, and raised thresholds ` +
+      'or ignore globs are not a fix.',
+    `Rule reference: ${RULES_DOC}`,
+  );
+  return lines.join('\n');
+}
+
+/** Other places a cloned block occurs: the finding's own line is the first. */
+function alsoAt(finding) {
+  const occurrences = finding.data?.occurrences;
+  if (!Array.isArray(occurrences) || occurrences.length < 2) return '';
+  const rest = occurrences.slice(1);
+  const shown = rest.slice(0, 2).map((o) => `${o.file}:${o.startLine}-${o.endLine}`);
+  const more = rest.length > shown.length ? ` +${rest.length - shown.length} more` : '';
+  return `  (also ${shown.join(', ')}${more})`;
+}
+
+function plural(n, word) {
+  return `${n} ${word}${n === 1 ? '' : 's'}`;
+}
+
+const flag = process.argv.indexOf('--agent');
+const agent = AGENTS[flag === -1 ? 'default' : process.argv[flag + 1]] ?? AGENTS.default;
+let input = {};
+try {
+  input = JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  // No readable input: behave as a turn with nothing to check.
+}
+// Already sent back once this turn: one nudge, so a finding the user decides to
+// keep cannot loop the session.
+if (!agent.resumed(input)) {
+  const root = agent.root(input);
+  const context = typeof root === 'string' && root !== '' ? gate(root) : undefined;
+  if (context !== undefined) process.stdout.write(`${JSON.stringify(agent.answer(context))}\n`);
+}

package/llms.txt

@@ -6,18 +6,20 @@ Run without installing: `npx stopslop .`. Exit codes are `0` for a clear gate, `
 
 Dead-code settings live under `knip` in `stopslop.json` — a project's own `knip.json` or `package.json#knip` is never read. Nothing needs to be written up front: the run prints `config hints` from Knip naming the workspace or entry point that is missing, and dead code stays out of the score until they are resolved.
 
+Coding agents: this repository is a plugin for Claude Code (`/plugin marketplace add BaryshevRS/stopslop`), Codex (`codex plugin marketplace add BaryshevRS/stopslop`), and Cursor, and an extension for Gemini CLI. It adds the `stopslop` skill and a stop hook that hands the agent what its uncommitted changes added before it ends a turn. Other agents get the skill with `npx skills add BaryshevRS/stopslop`.
+
 ## Start here
 
 - [Overview, installation, CLI and badge](https://raw.githubusercontent.com/BaryshevRS/stopslop/main/README.md)
 - [Configuration reference](https://raw.githubusercontent.com/BaryshevRS/stopslop/main/docs/configuration.md)
 - [CI baselines, Git comparison, SARIF and agent reports](https://raw.githubusercontent.com/BaryshevRS/stopslop/main/docs/ci-and-automation.md)
+- [What each finding means and how to fix it](https://raw.githubusercontent.com/BaryshevRS/stopslop/main/docs/rules.md)
 - [Typed Node.js API](https://raw.githubusercontent.com/BaryshevRS/stopslop/main/docs/node-api.md)
 
 ## How it works
 
 - [Score formula and interpretation](https://raw.githubusercontent.com/BaryshevRS/stopslop/main/docs/score.md)
 - [Default thresholds and calibration](https://raw.githubusercontent.com/BaryshevRS/stopslop/main/docs/thresholds.md)
-- [Architecture and methodology](https://raw.githubusercontent.com/BaryshevRS/stopslop/main/ARCH.md)
 - [Compatibility policy](https://raw.githubusercontent.com/BaryshevRS/stopslop/main/COMPATIBILITY.md)
 
 ## Package

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stopslop",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Static analysis for AI-generated JavaScript and TypeScript: find cognitive complexity, god classes/modules, duplicate code, dead code and orphan features.",
   "type": "module",
   "license": "MIT",
@@ -29,6 +29,7 @@
   "files": [
     "dist/**/*",
     "docs/**/*.md",
+    "hooks/stop-gate.mjs",
     "README.md",
     "COMPATIBILITY.md",
     "LICENSE",
@@ -44,7 +45,7 @@
     "access": "public"
   },
   "scripts": {
-    "prebuild": "pnpm schema:check",
+    "prebuild": "pnpm schema:check && pnpm rules:check",
     "build": "tsdown",
     "dev": "tsdown --watch",
     "test": "vitest run",
@@ -59,6 +60,8 @@
     "typecheck": "tsc --noEmit",
     "schema:generate": "tsx scripts/generate-config-schema.ts",
     "schema:check": "tsx scripts/generate-config-schema.ts --check",
+    "rules:generate": "tsx scripts/generate-rules-doc.ts",
+    "rules:check": "tsx scripts/generate-rules-doc.ts --check",
     "commitlint": "commitlint",
     "prepare": "simple-git-hooks 1>&2"
   },
@@ -66,22 +69,22 @@
     "commit-msg": "pnpm exec commitlint --edit \"$1\""
   },
   "dependencies": {
-    "clone-alert": "^1.1.3",
-    "knip": "6.39.0",
-    "oxc-parser": "^0.139.0",
+    "clone-alert": "^1.1.5",
+    "knip": "6.44.1",
+    "oxc-parser": "^0.156.0",
     "picocolors": "^1.1.1"
   },
   "devDependencies": {
-    "@arethetypeswrong/core": "^0.18.1",
-    "@commitlint/cli": "^21.1.0",
-    "@commitlint/config-conventional": "^21.1.0",
-    "@types/node": "^22.10.0",
-    "publint": "^0.3.8",
-    "simple-git-hooks": "^2.13.1",
+    "@arethetypeswrong/core": "^0.18.5",
+    "@commitlint/cli": "^21.2.4",
+    "@commitlint/config-conventional": "^21.2.4",
+    "@types/node": "^22.20.5",
+    "publint": "^0.3.25",
+    "simple-git-hooks": "^2.14.0",
     "tsdown": "^0.21.10",
-    "tsx": "^4.19.0",
-    "typescript": "^5.7.0",
-    "vitest": "^3.0.0"
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.7"
   },
   "keywords": [
     "ai",

package/schema.json

@@ -842,6 +842,10 @@
               "title": "borp plugin configuration (https://knip.dev/reference/plugins/borp)",
               "$ref": "#/definitions/knip/definitions/plugin"
             },
+            "buf": {
+              "title": "buf plugin configuration (https://knip.dev/reference/plugins/buf)",
+              "$ref": "#/definitions/knip/definitions/plugin"
+            },
             "bumpp": {
               "title": "bumpp plugin configuration (https://knip.dev/reference/plugins/bumpp)",
               "$ref": "#/definitions/knip/definitions/plugin"
@@ -922,6 +926,10 @@
               "title": "Drizzle plugin configuration (https://knip.dev/reference/plugins/drizzle)",
               "$ref": "#/definitions/knip/definitions/plugin"
             },
+            "electron-forge": {
+              "title": "Electron Forge plugin configuration (https://knip.dev/reference/plugins/electron-forge)",
+              "$ref": "#/definitions/knip/definitions/plugin"
+            },
             "electron-vite": {
               "title": "electron-vite plugin configuration (https://knip.dev/reference/plugins/electron-vite)",
               "$ref": "#/definitions/knip/definitions/plugin"
@@ -950,6 +958,10 @@
               "title": "Expo plugin configuration (https://knip.dev/reference/plugins/expo)",
               "$ref": "#/definitions/knip/definitions/plugin"
             },
+            "expo-router": {
+              "title": "Expo Router plugin configuration (https://knip.dev/reference/plugins/expo-router)",
+              "$ref": "#/definitions/knip/definitions/plugin"
+            },
             "expressive-code": {
               "title": "expressive-code plugin configuration (https://knip.dev/reference/plugins/expressive-code)",
               "$ref": "#/definitions/knip/definitions/plugin"
@@ -958,6 +970,14 @@
               "title": "fast plugin configuration (https://knip.dev/reference/plugins/fast)",
               "$ref": "#/definitions/knip/definitions/plugin"
             },
+            "filesystem-routing": {
+              "title": "filesystem-routing plugin configuration (https://knip.dev/reference/plugins/filesystem-routing)",
+              "$ref": "#/definitions/knip/definitions/plugin"
+            },
+            "flue": {
+              "title": "flue plugin configuration (https://knip.dev/reference/plugins/flue)",
+              "$ref": "#/definitions/knip/definitions/plugin"
+            },
             "fumadocs": {
               "title": "fumadocs plugin configuration (https://knip.dev/reference/plugins/fumadocs)",
               "$ref": "#/definitions/knip/definitions/plugin"
@@ -990,6 +1010,10 @@
               "title": "i18next-parser plugin configuration (https://knip.dev/reference/plugins/i18next-parser)",
               "$ref": "#/definitions/knip/definitions/plugin"
             },
+            "jasmine": {
+              "title": "jasmine plugin configuration (https://knip.dev/reference/plugins/jasmine)",
+              "$ref": "#/definitions/knip/definitions/plugin"
+            },
             "jest": {
               "title": "Jest plugin configuration (https://knip.dev/reference/plugins/jest)",
               "$ref": "#/definitions/knip/definitions/plugin"
@@ -1002,6 +1026,10 @@
               "title": "knex plugin configuration (https://knip.dev/reference/plugins/knex)",
               "$ref": "#/definitions/knip/definitions/plugin"
             },
+            "kysely-codegen": {
+              "title": "kysely-codegen plugin configuration (https://knip.dev/reference/plugins/kysely-codegen)",
+              "$ref": "#/definitions/knip/definitions/plugin"
+            },
             "ladle": {
               "title": "ladle plugin configuration (https://knip.dev/reference/plugins/ladle)",
               "$ref": "#/definitions/knip/definitions/plugin"
@@ -1014,6 +1042,10 @@
               "title": "lefthook plugin configuration (https://knip.dev/reference/plugins/lefthook)",
               "$ref": "#/definitions/knip/definitions/plugin"
             },
+            "lingui": {
+              "title": "lingui plugin configuration (https://knip.dev/reference/plugins/lingui)",
+              "$ref": "#/definitions/knip/definitions/plugin"
+            },
             "lint-staged": {
               "title": "lint-staged plugin configuration (https://knip.dev/reference/plugins/lint-staged)",
               "$ref": "#/definitions/knip/definitions/plugin"
@@ -1046,6 +1078,14 @@
               "title": "marko plugin configuration (https://knip.dev/reference/plugins/marko)",
               "$ref": "#/definitions/knip/definitions/plugin"
             },
+            "mastra": {
+              "title": "mastra plugin configuration (https://knip.dev/reference/plugins/mastra)",
+              "$ref": "#/definitions/knip/definitions/plugin"
+            },
+            "mcp": {
+              "title": "mcp plugin configuration (https://knip.dev/reference/plugins/mcp)",
+              "$ref": "#/definitions/knip/definitions/plugin"
+            },
             "mdx": {
               "title": "mdx plugin configuration (https://knip.dev/reference/plugins/mdx)",
               "$ref": "#/definitions/knip/definitions/plugin"
@@ -1158,6 +1198,10 @@
               "title": "orval plugin configuration (https://knip.dev/reference/plugins/orval)",
               "$ref": "#/definitions/knip/definitions/plugin"
             },
+            "osls": {
+              "title": "osls plugin configuration (https://knip.dev/reference/plugins/osls)",
+              "$ref": "#/definitions/knip/definitions/plugin"
+            },
             "oxfmt": {
               "title": "oxfmt plugin configuration (https://knip.dev/reference/plugins/oxfmt)",
               "$ref": "#/definitions/knip/definitions/plugin"
@@ -1218,6 +1262,10 @@
               "title": "Prisma plugin configuration (https://knip.dev/reference/plugins/prisma)",
               "$ref": "#/definitions/knip/definitions/plugin"
             },
+            "purgecss": {
+              "title": "purgecss plugin configuration (https://knip.dev/reference/plugins/purgecss)",
+              "$ref": "#/definitions/knip/definitions/plugin"
+            },
             "quasar": {
               "title": "quasar plugin configuration (https://knip.dev/reference/plugins/quasar)",
               "$ref": "#/definitions/knip/definitions/plugin"
@@ -1310,6 +1358,10 @@
               "title": "size-limit plugin configuration (https://knip.dev/reference/plugins/size-limit)",
               "$ref": "#/definitions/knip/definitions/plugin"
             },
+            "solidjs-vite-plugin": {
+              "title": "solidjs-vite-plugin plugin configuration (https://knip.dev/reference/plugins/solidjs-vite-plugin)",
+              "$ref": "#/definitions/knip/definitions/plugin"
+            },
             "sst": {
               "title": "sst plugin configuration (https://knip.dev/reference/plugins/sst)",
               "$ref": "#/definitions/knip/definitions/plugin"
@@ -1402,6 +1454,10 @@
               "title": "tsdown plugin configuration (https://knip.dev/reference/plugins/tsdown)",
               "$ref": "#/definitions/knip/definitions/plugin"
             },
+            "tsrs": {
+              "title": "tsrs plugin configuration (https://knip.dev/reference/plugins/tsrs)",
+              "$ref": "#/definitions/knip/definitions/plugin"
+            },
             "tsup": {
               "title": "tsup plugin configuration (https://knip.dev/reference/plugins/tsup)",
               "$ref": "#/definitions/knip/definitions/plugin"