claude-crap 0.1.2

package/plugin/hooks/stop-quality-gate.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * claude-crap :: Stop / SubagentStop hook — final quality gate.
+ *
+ * When the agent (or a subagent) declares it is done with a task,
+ * this hook has the last word. It reads the consolidated SARIF
+ * report, estimates workspace LOC, computes the Technical Debt
+ * Ratio, and checks every configured policy:
+ *
+ *   - `SONAR-GATE-TDR`     — project TDR rating must not exceed
+ *                             the configured `TDR_MAX_RATING`.
+ *   - `SONAR-GATE-ERRORS`  — no SARIF finding at level "error" may
+ *                             survive.
+ *
+ * Strictness (v0.1.0):
+ *
+ *   The behavior on a failing verdict is controlled by the
+ *   workspace sonar configuration. Teams can adopt claude-crap in
+ *   stages by editing `.claude-crap.json` at their workspace root
+ *   or setting the `CLAUDE_CRAP_STRICTNESS` environment variable.
+ *   Three modes are supported:
+ *
+ *   - `strict` (default) — exit 2 with the full BLOCKED box on
+ *     stderr. Claude Code injects stderr into the agent's context,
+ *     so the agent must remediate before retrying the Stop hook.
+ *     This is the original, hard-failing behavior of the plugin.
+ *   - `warn`              — exit 0 with the full WARNING box on
+ *     stdout. The task is allowed to close, but the hook transcript
+ *     still carries every failing rule so the agent can choose to
+ *     remediate on its next turn.
+ *   - `advisory`          — exit 0 with a single-line ADVISORY note
+ *     on stdout. Minimal pressure on the agent.
+ *
+ *   A passing verdict always exits 0 and emits the same JSON status
+ *   line regardless of strictness.
+ *
+ * This hook deliberately lives outside the MCP server process so
+ * that it runs deterministically even if the server is momentarily
+ * disconnected. It imports the TDR classification functions
+ * directly from the compiled MCP server's `dist/` so the math is
+ * the single source of truth.
+ *
+ * @module hooks/stop-quality-gate
+ */
+
+import { ExitCodes, readStdinJson, runHook } from "./lib/hook-io.mjs";
+import { evaluateQualityGate, loadQualityGateConfig } from "./lib/quality-gate.mjs";
+import {
+  DEFAULT_STRICTNESS,
+  loadCrapConfig,
+  CrapConfigError,
+} from "./lib/crap-config.mjs";
+
+/**
+ * Resolve the effective strictness for this Stop hook invocation.
+ * Falls back to {@link DEFAULT_STRICTNESS} on any loader error so a
+ * busted `.claude-crap.json` never deadlocks the user — the file
+ * error is logged to stderr for diagnostics but the gate still
+ * runs.
+ *
+ * @param {string} workspaceRoot Absolute path to the user's workspace.
+ * @returns {{strictness: import("./lib/crap-config.mjs").Strictness, source: "env" | "file" | "default" | "fallback"}}
+ */
+function resolveStrictness(workspaceRoot) {
+  try {
+    const config = loadCrapConfig({ workspaceRoot });
+    return { strictness: config.strictness, source: config.strictnessSource };
+  } catch (err) {
+    if (err instanceof CrapConfigError) {
+      process.stderr.write(
+        `[claude-crap] Stop hook: ${err.message}\n` +
+          `[claude-crap] falling back to strictness='${DEFAULT_STRICTNESS}' for this run.\n`,
+      );
+      return { strictness: DEFAULT_STRICTNESS, source: "fallback" };
+    }
+    throw err;
+  }
+}
+
+/**
+ * Render the failing verdict as the existing BLOCKED box used by
+ * `strict` mode. Keeps the shape stable so strict-mode users see
+ * exactly the same output as before this feature landed.
+ *
+ * @param {import("./lib/quality-gate.mjs").GateVerdict} verdict
+ * @returns {string}
+ */
+function renderBlockedBox(verdict) {
+  return renderVerdictBox(verdict, "BLOCKED");
+}
+
+/**
+ * Render the failing verdict as a WARNING box. Same information
+ * density as the BLOCKED box, but the header changes so agents and
+ * humans can distinguish a blocking gate from an advisory one.
+ *
+ * @param {import("./lib/quality-gate.mjs").GateVerdict} verdict
+ * @returns {string}
+ */
+function renderWarningBox(verdict) {
+  return renderVerdictBox(verdict, "WARNING");
+}
+
+/**
+ * Render a single-line advisory note. Used by `advisory` mode so
+ * the agent is informed of the quality state without being pushed
+ * into a remediation loop.
+ *
+ * @param {import("./lib/quality-gate.mjs").GateVerdict} verdict
+ * @returns {string}
+ */
+function renderAdvisoryLine(verdict) {
+  const { summary, failures } = verdict;
+  const ruleIds = failures.map((f) => f.ruleId).join(", ") || "<none>";
+  return (
+    `claude-crap :: Stop quality gate ADVISORY — ${failures.length} policy note(s). ` +
+    `TDR ${summary.tdrPercent}% (rating ${summary.tdrRating}), ` +
+    `${summary.errorFindings} error / ${summary.warningFindings} warning / ${summary.noteFindings} note, ` +
+    `rules: ${ruleIds}. This was an advisory run — the task may close.`
+  );
+}
+
+/**
+ * Shared renderer for the BLOCKED and WARNING variants. The only
+ * difference between them is the header label and the explanatory
+ * sentence at the top.
+ *
+ * @param {import("./lib/quality-gate.mjs").GateVerdict} verdict
+ * @param {"BLOCKED" | "WARNING"} label
+ * @returns {string}
+ */
+function renderVerdictBox(verdict, label) {
+  const { summary, failures } = verdict;
+  const header = [
+    `╭─ claude-crap :: Stop quality gate ${label} ─────────────────────`,
+    `│ total findings      : ${summary.totalFindings}`,
+    `│   error / warn / note: ${summary.errorFindings} / ${summary.warningFindings} / ${summary.noteFindings}`,
+    `│ remediation minutes : ${summary.remediationMinutes}`,
+    `│ workspace LOC       : ${summary.physicalLoc}`,
+    `│ TDR                 : ${summary.tdrPercent}%  →  rating ${summary.tdrRating}`,
+    `│ tools seen          : ${summary.toolsSeen.join(", ") || "<none>"}`,
+    `│`,
+    `│ ${failures.length} policy failure(s):`,
+    `│`,
+  ];
+  /** @type {string[]} */
+  const body = [];
+  failures.forEach((f, idx) => {
+    body.push(`│ [${idx + 1}] ${f.ruleId}`);
+    for (const line of f.message.split("\n")) {
+      body.push(`│     ${line}`);
+    }
+    body.push(`│`);
+  });
+  const footer = [`╰──────────────────────────────────────────────────────────────────`];
+  return [...header, ...body, ...footer].join("\n");
+}
+
+async function main() {
+  // We read stdin so hook consumers see we honored the contract,
+  // but the Stop hook does not actually need per-call state — the
+  // verdict is entirely derived from the on-disk SARIF and the
+  // workspace.
+  await readStdinJson().catch(() => ({}));
+
+  const gateConfig = loadQualityGateConfig();
+  const verdict = await evaluateQualityGate(gateConfig);
+
+  // A passing verdict always exits 0 with the same status line
+  // regardless of strictness — the feature only changes the FAILING
+  // path.
+  if (verdict.passed) {
+    process.stdout.write(
+      JSON.stringify({
+        status: "passed",
+        gate: "stop",
+        summary: verdict.summary,
+      }) + "\n",
+    );
+    process.exit(ExitCodes.ALLOW);
+    return;
+  }
+
+  const { strictness } = resolveStrictness(gateConfig.workspaceRoot);
+
+  if (strictness === "strict") {
+    // Hard block: render the BLOCKED box to stderr so Claude Code
+    // injects it into the agent's context, then exit 2.
+    process.stderr.write(renderBlockedBox(verdict) + "\n");
+    process.exit(ExitCodes.BLOCK);
+    return;
+  }
+
+  if (strictness === "warn") {
+    // Soft nudge: render the WARNING box to stdout so it lands in
+    // the hook transcript and the agent still sees every failing
+    // rule, then exit 0 so the task is allowed to close.
+    process.stdout.write(renderWarningBox(verdict) + "\n");
+    process.stdout.write(
+      JSON.stringify({
+        status: "warning",
+        gate: "stop",
+        strictness: "warn",
+        summary: verdict.summary,
+      }) + "\n",
+    );
+    process.exit(ExitCodes.ALLOW);
+    return;
+  }
+
+  // strictness === "advisory"
+  // Minimal pressure: single-line note on stdout, then exit 0.
+  process.stdout.write(renderAdvisoryLine(verdict) + "\n");
+  process.stdout.write(
+    JSON.stringify({
+      status: "advisory",
+      gate: "stop",
+      strictness: "advisory",
+      summary: verdict.summary,
+    }) + "\n",
+  );
+  process.exit(ExitCodes.ALLOW);
+}
+
+runHook("Stop quality gate", main);

package/plugin/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "claude-crap-plugin",
+  "version": "0.1.2",
+  "private": true,
+  "description": "Runtime dependencies for the claude-crap plugin bundle",
+  "type": "module",
+  "dependencies": {
+    "@fastify/static": "^8.0.3",
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "fastify": "^5.2.0",
+    "pino": "^9.5.0",
+    "tree-sitter-wasms": "^0.1.12",
+    "web-tree-sitter": "^0.24.4"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/plugin/skills/adopt/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: adopt
+description: Interactive onboarding walkthrough for teams introducing claude-crap on an existing codebase. Use this skill whenever the user asks "how do I install claude-crap on my project", "we're adopting claude-crap for our team", "how should I roll claude-crap out", "what strictness mode should I pick", "we have a lot of legacy code, can we ease into this gradually", "our project has a bunch of existing errors, how do I avoid getting blocked", or is otherwise looking for guidance on gradual rollout strategy instead of just dropping a strict quality gate on a messy codebase. The skill asks a short three-question assessment about test coverage, existing findings, and appetite for hard enforcement, recommends one of three strictness modes (advisory / warn / strict), and emits a copy-pasteable .claude-crap.json snippet for the workspace root so the team can commit the policy in a single step.
+---
+
+# Help a team adopt claude-crap gradually
+
+Walk the user through picking the right initial strictness mode for claude-crap on their workspace, then hand them the exact `.claude-crap.json` to commit. The whole interaction should take under two minutes — it is an onboarding assistant, not a full quality audit.
+
+## Interview
+
+Ask the user these three questions, one at a time. Wait for each answer before moving to the next so the user is not overwhelmed.
+
+1. **"How much existing test coverage does your workspace have — would you call it green (80%+, most modules are tested), patchy (some well-tested, some bare), or near-zero?"**
+2. **"Have you run any SAST or quality scanners on the workspace recently — Semgrep, ESLint with security rules, Bandit, Stryker, anything like that? Roughly how many `error`-level findings would a fresh scan produce: zero, a handful (say 1–5), or more than that?"**
+3. **"Does the team want claude-crap to hard-block task closures from day one, or would you rather see the quality verdict for a week first and decide to enforce it later?"**
+
+## Recommendation logic
+
+Pick the strictness using this table. The principle is simple: if the project would immediately red-light under strict mode, don't start there — the team will just disable the plugin. Start at the loosest mode that still surfaces the findings, and tighten over time.
+
+| Test coverage | Existing error findings | Wants hard block from day one? | Recommend   |
+| :------------ | :---------------------- | :----------------------------- | :---------- |
+| Green         | 0                       | Yes                            | `strict`    |
+| Green         | 0                       | No / unsure                    | `warn`      |
+| Green         | 1–5                     | Either                         | `warn`      |
+| Patchy        | 0                       | Either                         | `warn`      |
+| Patchy        | 1–5                     | Either                         | `advisory`  |
+| Patchy        | 6+                      | Either                         | `advisory`  |
+| Near-zero     | Any                     | Any                            | `advisory`  |
+
+If the user's answers fall outside the table exactly, lean toward the looser mode. Rolling out tight and loosening is painful; rolling out loose and tightening is natural.
+
+## Produce the config
+
+Output the recommended `.claude-crap.json` in a fenced JSON code block. Use this exact shape, substituting `<recommended-mode>` with the actual value from the table (`strict`, `warn`, or `advisory`):
+
+```jsonc
+// .claude-crap.json — commit this to the workspace root
+{
+  "$schema": "https://raw.githubusercontent.com/ahernandez-developer/claude-crap/main/schemas/crap-config.json",
+  "strictness": "<recommended-mode>"
+}
+```
+
+Then explain what happens in the mode you picked, in one sentence per mode:
+
+- **strict**: The Stop hook exits 2 on any policy failure. The full verdict is injected into the agent's context via stderr, and the task cannot close until the rules are satisfied. Use this when you want claude-crap to enforce the same way CI would.
+- **warn**: The Stop hook exits 0 but writes the full verdict to stdout so the agent still sees every failing rule in its hook transcript. The task is allowed to close, and the agent can choose to remediate voluntarily on the next turn. Use this when you want pressure without blocking.
+- **advisory**: The Stop hook exits 0 and writes a one-line summary to stdout. Minimal pressure on the agent — the task closes with a soft nudge. Use this when you're just collecting data and want the team to see the quality readings before enforcing anything.
+
+## Follow-up roadmap
+
+End with a one-paragraph gradual-adoption roadmap tailored to the mode you picked:
+
+1. **Commit `.claude-crap.json`** to the workspace root so the whole team picks up the policy.
+2. **Let the team run for 1–2 weeks** in that mode, reviewing the local Vue dashboard at `http://127.0.0.1:5117` to see the SARIF findings accumulate.
+3. **Tighten the mode by one step** (`advisory` → `warn` → `strict`) once the team is comfortable with what they're seeing and the finding count is trending down.
+4. **Advanced tip**: any team member can override per-session with `CLAUDE_CRAP_STRICTNESS=<mode> claude` — useful for a one-off lenient run during an emergency, without changing the committed policy.
+
+## Why this skill exists
+
+Adopting a deterministic quality gate on an existing codebase is a change-management problem more than a technical one. Teams that jump straight to `strict` mode without checking their baseline tend to hit a wall the first time the Stop hook blocks a task close, get frustrated, and disable the plugin — losing all the benefit of the PreToolUse gatekeeper and the PostToolUse verifier too, which would have worked fine at their current codebase.
+
+This skill turns the adoption question into a 30-second assessment and a ready-to-commit config. The three questions are deliberately minimal: they capture the only signals that actually matter for picking an initial mode (coverage, baseline findings, enforcement appetite), and they avoid the overhead of running a full scan before the team has even installed the plugin.
+
+The gradual-adoption roadmap is the other half of the value: most teams never pick the "right" strictness on the first try, and the skill's job is to leave them with a clear path to tighten over time instead of a one-shot recommendation they'll regret in a month.
+
+## Do not
+
+- Do not recommend `strict` mode to a team that has any unresolved `error`-level findings in a recent scan. That is a guaranteed rage-quit on the first task close.
+- Do not skip the interview questions. The whole point is that the recommendation matches the team's actual situation, not some default assumption about what they "should" want.
+- Do not output a placeholder like `<recommended-mode>` in the JSON code block. Fill it with the actual value from the table so the user can copy-paste directly without editing.
+- Do not run `score_project` as part of this skill. The interview is faster and gives the team more control over the recommendation than a baseline scan would. Reach for `/claude-crap:score` separately if they ask for hard numbers.

package/plugin/skills/analyze/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: analyze
+description: Run tree-sitter AST analysis on a source file using claude-crap's deterministic engine and report per-function cyclomatic complexity plus physical and logical lines of code. Use this skill whenever the user asks "what's the complexity of this file", "how complex is foo.ts", "show me cyclomatic complexity per function", "analyze this file's structure", "which functions in this file are too complex", "where should I refactor first in this module", or needs to pick candidates for refactoring based on complexity. Also use this skill proactively when a file feels "big" and you want a ranked list of hot-spot functions before proposing a refactor plan — the tree-sitter engine gives exact numbers instead of eyeball estimates. Supports TypeScript, JavaScript, Python, Java, and C#; the language is detected automatically from the file extension. Takes a single file path as the argument after the skill name.
+---
+
+# Analyze a source file with tree-sitter
+
+Run the `analyze_file_ast` MCP tool from the claude-crap server against a user-supplied file and report deterministic AST metrics.
+
+## Arguments
+
+The user supplies a file path as the argument, typed after the skill name:
+
+```
+/claude-crap:analyze src/index.ts
+/claude-crap:analyze app/main.py
+/claude-crap:analyze lib/foo.cs
+```
+
+## Steps
+
+1. **Parse the file path**. Take `$ARGUMENTS` as the path. Reject it with a friendly one-liner if it contains `../` — the server's workspace guard will reject path traversal attempts regardless, but failing fast in the skill is cleaner than surfacing a stack trace from the MCP layer.
+
+2. **Detect the language from the extension**. Use this table:
+
+   | Extension                                   | `language` argument |
+   | :------------------------------------------ | :------------------ |
+   | `.ts` / `.tsx` / `.mts` / `.cts`            | `typescript`        |
+   | `.js` / `.jsx` / `.mjs` / `.cjs`            | `javascript`        |
+   | `.py`                                       | `python`            |
+   | `.java`                                     | `java`              |
+   | `.cs`                                       | `csharp`            |
+
+   If the extension does not map to one of those five, tell the user which languages are supported and do not invoke the tool. Claude-sonar's tree-sitter engine is language-scoped; there is no "auto-detect from content" mode.
+
+3. **Invoke the MCP tool** `analyze_file_ast` with `filePath: "$ARGUMENTS"` and the detected `language`.
+
+4. **Display file-level metrics first**: physical LOC (every newline-terminated line including blanks and comments) and logical LOC (lines with at least one non-whitespace character). The delta between the two is an informal "comment density" signal.
+
+5. **Display a ranked function list**, sorted by cyclomatic complexity descending. For each function, show:
+   - Function name (or `<anonymous>` if the tree-sitter grammar could not resolve a name)
+   - Start line → end line
+   - Cyclomatic complexity
+   - Physical line count (`endLine - startLine + 1`)
+
+6. **Flag refactoring candidates**. Any function whose cyclomatic complexity exceeds `15` (the plugin's default `cyclomaticMax`) is a Stop-gate warning candidate — call those out explicitly as "above the cyclomatic ceiling; refactor candidate". A function above `30` will fail the CRAP quality gate regardless of coverage and MUST be decomposed; those are the highest-priority targets.
+
+7. **Handle errors gracefully**. If the tool returns `status: "error"`, the most likely cause is a tree-sitter grammar that failed to load (`Could not load wasm grammar for language X`). Tell the user they may need to reinstall the plugin via `/plugin install claude-crap@herz` so the bundled WASM grammars are re-extracted into the plugin cache.
+
+## What the user will see
+
+A compact report along the lines of:
+
+```
+src/index.ts — 658 LOC (512 logical)
+
+Functions ranked by cyclomatic complexity:
+  1. handleRequest      lines 120–245  CC=22  (126 lines)   ⚠ above cyclomatic ceiling (15)
+  2. parseBody           lines  48–102  CC=14  ( 55 lines)
+  3. sendResponse        lines 300–340  CC= 9  ( 41 lines)
+  4. init                lines  10–30   CC= 3  ( 21 lines)
+
+⚠ `handleRequest` has CC=22 (ceiling is 15). Refactor candidate.
+```
+
+Exact formatting can vary — the important thing is that the function list is ranked and the refactoring candidates are called out explicitly.
+
+## Why this skill exists
+
+The `analyze_file_ast` MCP tool is the deterministic alternative to "Claude reads the file and estimates complexity." Manual complexity estimation is a known failure mode for LLMs — we overcount branches, we undercount nested constructs, and we are not self-consistent across runs. The tree-sitter engine gives exact, reproducible per-function metrics that the user can trust for refactoring decisions, and the numbers match what the Stop quality gate will eventually grade against, so using this tool up-front closes the loop between exploration and enforcement.
+
+## Do not
+
+- Do not invoke this skill for files outside the workspace. The workspace guard will reject them; use a workspace-relative path.
+- Do not compute cyclomatic complexity by reading the file and counting branches yourself. The tree-sitter engine is the single source of truth. If the user disagrees with the number, the disagreement is almost always a misunderstanding of where a branch lives in the AST, not a bug in the engine.
+- Do not refactor based on eyeball estimates of complexity when this tool is available. A refactor proposal that cites "handleRequest is too complex" without an exact CC number is not actionable.
+- Do not invoke the skill on a minified file — the numbers will be meaningless (the whole file is one "function" to the parser). Minified artifacts belong in `.gitignore`, not in the analyzer.

package/plugin/skills/check-test/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: check-test
+description: Check whether a production source file has an accompanying characterization test using claude-crap's deterministic test-harness resolver. Use this skill whenever the user asks "is this file tested", "does foo.ts have a test", "where's the test for bar.py", "check test coverage for this file", "do I have a test harness for src/baz.java", or is about to modify a source file and wants to know if the CLAUDE.md Golden Rule test prerequisite is already satisfied. Use it proactively at the start of any work on a .ts / .tsx / .js / .jsx / .mjs / .cjs / .py / .java / .cs file to verify a characterization test exists — this is required by CLAUDE.md and claude-crap's PostToolUse hook will flag the violation later if you skip the check. The skill takes a single file-path argument after the skill name.
+---
+
+# Check the test harness for a file
+
+Run the `require_test_harness` MCP tool from the claude-crap server against a user-supplied file path and report whether a matching test exists.
+
+## Arguments
+
+The user supplies a file path as the argument, typed after the skill name:
+
+```
+/claude-crap:check-test src/foo/bar.ts
+/claude-crap:check-test pkg/mod.py
+/claude-crap:check-test app/src/main/java/com/example/Service.java
+```
+
+Pass `$ARGUMENTS` verbatim as the `filePath` argument to the MCP tool. Do not normalize, strip quotes, or resolve the path yourself — the server's workspace guard handles that.
+
+## Steps
+
+1. Invoke the MCP tool `require_test_harness` with `filePath: "$ARGUMENTS"`.
+2. If the tool returns `hasTest: true`:
+   - Tell the user the test file path from the `testFile` field, formatted as a clickable relative path.
+   - If `isTestFile: true`, note that the user's input was itself already a test file — the resolver short-circuited. This usually means the user meant to ask about a different file; suggest they re-run the skill with the production file path.
+3. If the tool returns `hasTest: false`:
+   - Tell the user no matching test was found.
+   - Remind them that CLAUDE.md's Golden Rule forbids writing functional code in this file until a characterization test exists — that's the plugin's core contract.
+   - List the first 3 paths from the `candidates` array as suggested locations for the new test. These are ordered by the resolver's convention priority: sibling `<name>.test.<ext>` first, then `__tests__/<name>.test.<ext>`, then mirror-tree layouts under `tests/`, `test/`, and `__tests__/` at the workspace root, then the nearest-ancestor flat `tests/` directory, then Python `test_<name>.py` variants. Suggest the highest-priority candidate that matches the project's existing conventions — if you can see other test files in the repo, pick the layout that matches them.
+4. If the tool returns an error (`status: "error"`):
+   - The most common cause is a path that escapes the workspace root. Tell the user to use a workspace-relative path (e.g. `src/foo.ts`, not `../other-repo/foo.ts`).
+   - The second-most-common cause is a typo in the file path. Ask them to double-check the path exists.
+
+## What the user will see
+
+A one-line verdict ("Test found: `src/foo.test.ts`" or "No test found") followed by guidance on what to do next. For the "no test" case, the list of candidate paths is the most valuable thing — it tells the user exactly where the plugin's resolver expects the test to live, without them having to read the resolver source.
+
+## Why this skill exists
+
+The Golden Rule in CLAUDE.md forbids writing functional code before a characterization test exists. The `require_test_harness` tool is the deterministic check for that prerequisite, and it is wired into the PostToolUse hook to catch violations after the fact. But a pre-flight check before starting work on a file is cheaper than fighting the PostToolUse warning later — the user can decide up front whether to write the test first or pick a different file.
+
+The resolver understands seven conventions (sibling, `__tests__`, mirror tree, nearest-ancestor flat `tests/`, Python `test_` prefix, and two more) so it works across the five languages the plugin supports without requiring the user to configure anything.
+
+## Do not
+
+- Do not guess at test file locations. The resolver enumerates every convention claude-crap supports — if it returns `hasTest: false`, a matching test genuinely does not exist yet.
+- Do not suggest the user rename an existing spec file to match the convention. Instead, create a new test file at the highest-priority candidate path so the existing test remains in place if other tooling depends on its name.
+- Do not invoke the skill with an absolute path that points outside the workspace. The workspace guard will reject it, and the user will be confused about why.

package/plugin/skills/score/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: score
+description: Run claude-crap's deterministic project quality gate and display the A..E letter grade across Maintainability, Reliability, Security, and Overall. Use this skill whenever the user asks "how's the code quality", "what's my CRAP index", "is this project shippable", "show me the technical debt ratio", "run the quality gate", "score the project", or wants a one-glance read on whether the current workspace passes its policy ceiling. Also use this skill proactively at the start of a refactoring session or before a release to establish a quality baseline, and after a substantial refactor to verify the grade has not regressed. Do NOT use it for incident debugging or per-file analysis — for a single file, reach for /claude-crap:analyze instead.
+---
+
+# Score the project
+
+Run the `score_project` MCP tool from the claude-crap server and display the result.
+
+## Steps
+
+1. Invoke the MCP tool `score_project` with `format: "both"` so you get both the Markdown summary and the JSON snapshot in one call.
+2. Display the Markdown summary verbatim. Do not paraphrase, round, or reorder the dimension ratings — they are deterministic, they come directly from the CRAP / TDR / rating engines, and they must be shown exactly as the engine produced them so the user can verify against the dashboard.
+3. If the tool response has `isError: true`, the overall rating is worse than the configured policy ceiling under strict mode. Explicitly tell the user their workspace **FAILS** the policy, surface the rule IDs from the failures array (e.g. `SONAR-GATE-TDR`, `SONAR-GATE-ERRORS`), and recommend they drill into the dashboard URL or the consolidated SARIF report to see the underlying findings.
+4. If the tool succeeds, tell the user the dashboard URL from the Markdown content so they can open it in a browser for per-file hot spots, and the SARIF report path so they can grep it with other tools if they prefer.
+
+## What the user will see
+
+The output includes four A..E letter grades (one per dimension plus an overall), the TDR percent, per-level finding counts, workspace LOC, the scanners that have already ingested findings, the dashboard URL, and the SARIF report path. The overall grade is the worst of the three dimension grades by policy, so a single E-rated security finding drops the whole score to E regardless of maintainability.
+
+## Why this skill exists
+
+The `score_project` MCP tool is the canonical "is this project shippable?" reading for claude-crap. It gets run automatically at the Stop quality gate on every task close, but users often want an ad-hoc read mid-session — to know whether a refactor actually improved the grade, to get a baseline before starting new work, or to decide whether to open a PR now or keep iterating. Making it a single slash command instead of a three-step MCP tool invocation removes the friction from those workflows.
+
+The engine is deterministic: given the same SARIF store and the same workspace, `score_project` always returns the same grade. That is a feature, not a limitation — it means two developers on the same branch will see identical readings, and it means the grade is safe to cite in PR descriptions and commit messages without the usual LLM caveats about reproducibility.
+
+## Do not
+
+- Do not compute CRAP or TDR by hand, or estimate the grade "based on what you've seen of the codebase". The only valid answer is what `score_project` returns.
+- Do not suggest remediations that aren't grounded in the SARIF findings the tool reports. If the Security dimension is D, open the SARIF file and read the rule IDs before recommending fixes — do not speculate.
+- Do not hide the dashboard URL. Users rely on it to drill into the detail the Markdown summary necessarily elides.