@stupify/cli 0.0.7 → 0.0.8

package/dist/analysis.js

@@ -71,10 +71,14 @@ function uncheckedSearchMatches(value, contexts) {
                 targetId,
                 patternId: context.checkId,
                 reason: match.reason ?? "",
-                proof: match.proof ?? "",
+                proof: sourcePointer(context),
             }];
     });
 }
+function sourcePointer(context) {
+    const file = context.filePath ?? "(unknown)";
+    return `${file}::${context.entityKind || "entity"}::${context.entityName || context.entityId}`;
+}
 async function runJsonPrompt(model, prompt, schema, temperature) {
     return cachedJson("model-json", fingerprint({
         version: 1,

package/dist/checks.js

@@ -4,6 +4,7 @@ export const defaultChecks = [
         id: checkId("duplicated_schema"),
         name: "Duplicated schema",
         question: "Did the change duplicate an existing type, schema, payload, or DTO shape?",
+        why: "Duplicated shapes make it easier for AI-assisted changes to drift away from the real source of truth.",
         lookFor: [
             "local shape mirrors existing fields and maps them one-for-one",
             "new response, payload, schema, or DTO adds no filtering, renaming, validation, or versioning",
@@ -28,6 +29,7 @@ export const defaultChecks = [
         id: checkId("unnecessary_complexity"),
         name: "Unnecessary complexity",
         question: "Did the change add structure without buying clarity?",
+        why: "Extra indirection can hide simple decisions and make the code feel more designed than understood.",
         lookFor: [
             "helper, wrapper, service, layer, or extra file around simple logic without reuse",
         ],
@@ -68,6 +70,7 @@ Prefer no match over a weak match.`,
         id: checkId("fake_precision_windowing"),
         name: "Fake precision windowing",
         question: "Did the change add fake precision around model context?",
+        why: "Precise-looking bookkeeping can create confidence without improving the actual behavior.",
         lookFor: [
             "precise-looking counts, budgets, ratios, reports, or batching fields without useful behavior",
         ],
@@ -80,6 +83,7 @@ Prefer no match over a weak match.`,
         id: checkId("coauthored_slop"),
         name: "Coauthored slop",
         question: "Does author metadata contain co-author text?",
+        why: "Careless metadata is a cheap signal that the change may not have been reviewed with intent.",
         lookFor: [
             "author signal contains coauhtoried, coauthored, or co-authored text",
         ],
@@ -91,6 +95,7 @@ Prefer no match over a weak match.`,
         id: checkId("mega_file"),
         name: "Mega file",
         question: "Is a touched non-config file over 1000 LOC?",
+        why: "Large files make judgment harder by concentrating unrelated decisions in one place.",
         lookFor: [
             "touched non-config source file over 1000 LOC",
         ],
@@ -102,6 +107,7 @@ Prefer no match over a weak match.`,
         id: checkId("over_commenting"),
         name: "Over commenting",
         question: "Did the change add noisy comments?",
+        why: "Narrative comments can make routine code look deliberate without clarifying the underlying tradeoff.",
         lookFor: [
             "comments restate obvious code or narrate simple logic",
         ],
@@ -129,6 +135,7 @@ Prefer no match over a weak match.`,
         id: checkId("lint_bypass"),
         name: "Lint bypass",
         question: "Did the change bypass lint or type rules?",
+        why: "Unexplained suppressions remove useful feedback exactly where a change needs more scrutiny.",
         lookFor: [
             "adds suppressions, any, broad casts, or weakens lint/typecheck config",
         ],
@@ -152,6 +159,7 @@ Prefer no match over a weak match.`,
         id: checkId("inconsistent_patterns"),
         name: "Inconsistent patterns",
         question: "Does the change clash with nearby patterns?",
+        why: "Pattern drift can signal that a change followed generic suggestions instead of local codebase judgment.",
         lookFor: [
             "same job uses different naming, errors, state, imports, or layout than nearby files",
         ],
@@ -164,6 +172,7 @@ Prefer no match over a weak match.`,
         id: checkId("reinvented_utils"),
         name: "Reinvented utils",
         question: "Did the change recreate an existing utility?",
+        why: "Generic helper reinvention can be a sign that the change optimized for plausible code over local reuse.",
         lookFor: [
             "new helper duplicates local utility or standard library behavior",
         ],
@@ -188,6 +197,7 @@ Prefer no match over a weak match.`,
         id: checkId("operator_style_mismatch"),
         name: "Operator style mismatch",
         question: "Does the change read unlike the surrounding code?",
+        why: "Style mismatch can reveal generic generated code that was not reconciled with nearby conventions.",
         lookFor: [
             "generic or template-like names, abstractions, comments, or control flow clash with local style",
         ],

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.0.7";
+export declare const VERSION = "0.0.8";
 import type { ModelConfig, ModelId } from "./types.ts";
 export declare const DEFAULT_MODEL_ID: ModelId;
 export declare const MODEL_REGISTRY: Record<ModelId, ModelConfig>;

package/dist/constants.js

@@ -1,4 +1,4 @@
-export const VERSION = "0.0.7";
+export const VERSION = "0.0.8";
 export const DEFAULT_MODEL_ID = "gemma-4-e2b";
 export const MODEL_REGISTRY = {
     "gemma-4-e2b": {

package/dist/prompts.js

@@ -55,6 +55,7 @@ ${input.pack.text || "(none)"}`;
 }
 function formatSearchPattern(check) {
     return `Pattern: ${check.id} (${check.name})
+Why this matters: ${check.why}
 Question: ${check.searchPrompt ?? check.question}
 Look for:
 ${check.lookFor.map((signal) => `- ${signal}`).join("\n")}
@@ -81,6 +82,7 @@ function patternForContext(context, patterns) {
         id: context.checkId,
         name: context.checkId,
         question: `Does this target match ${context.checkId}?`,
+        why: "This pattern may indicate judgment-offload.",
         lookFor: [],
         ignoreWhen: [],
     };

package/dist/render.js

@@ -29,7 +29,8 @@ No judgment-offload signals found.`;
     return `🧙 stupify 🪄
 Possible judgment-offload detected:
 ${run.matches.map((match, index) => `${index + 1}. ${match.patternId}
-   ${match.reason}
+   Why: ${match.checkWhy ?? "This pattern may indicate judgment-offload."}
+   Match: ${match.reason}
    Proof: ${match.proof}`).join("\n")}
 Search mode is warn-only.`;
 }

package/dist/stupify.js

@@ -198,7 +198,7 @@ export async function runSearchCommand(command, startedAt) {
             }
             const { value } = await t.trace("search.model", () => runSearch(model, batch.request), { count: (v) => v.length });
             modelCalls += 1;
-            matches.push(...value);
+            matches.push(...withCheckWhy(value, checks));
         }
         const uniqueMatches = dedupeMatches(matches);
         return {
@@ -242,6 +242,13 @@ function dedupeMatches(matches) {
         return true;
     });
 }
+function withCheckWhy(matches, checks) {
+    const checksById = new Map(checks.map((check) => [check.id, check]));
+    return matches.map((match) => ({
+        ...match,
+        checkWhy: checksById.get(match.patternId)?.why,
+    }));
+}
 async function buildSearchBatches(input) {
     const first = makeSearchBatch(input, input.contexts, input.initialPack);
     if (first.estimatedInputTokens <= input.maxSearchInputTokens) {

package/dist/types.d.ts

@@ -68,6 +68,7 @@ export type StupifyCheck = Readonly<{
     id: CheckId;
     name: string;
     question: string;
+    why: string;
     lookFor: readonly string[];
     ignoreWhen: readonly string[];
     enabledByDefault?: boolean;
@@ -194,6 +195,7 @@ export type SearchProfile = Readonly<{
 export type SearchMatch = Readonly<{
     targetId: string;
     patternId: CheckId;
+    checkWhy?: string;
     reason: string;
     proof: string;
 }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stupify/cli",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Local-only diagnostic CLI for checking whether AI is making you dumber.",
   "private": false,
   "type": "module",

package/src/analysis.ts

@@ -104,11 +104,16 @@ function uncheckedSearchMatches(value: unknown, contexts: readonly SemContext[])
       targetId,
       patternId: context.checkId,
       reason: match.reason ?? "",
-      proof: match.proof ?? "",
+      proof: sourcePointer(context),
     }];
   });
 }
 
+function sourcePointer(context: SemContext): string {
+  const file = context.filePath ?? "(unknown)";
+  return `${file}::${context.entityKind || "entity"}::${context.entityName || context.entityId}`;
+}
+
 async function runJsonPrompt(
   model: LocalModel,
   prompt: string,

package/src/checks.ts

@@ -5,6 +5,7 @@ export const defaultChecks: readonly StupifyCheck[] = [
     id: checkId("duplicated_schema"),
     name: "Duplicated schema",
     question: "Did the change duplicate an existing type, schema, payload, or DTO shape?",
+    why: "Duplicated shapes make it easier for AI-assisted changes to drift away from the real source of truth.",
     lookFor: [
       "local shape mirrors existing fields and maps them one-for-one",
       "new response, payload, schema, or DTO adds no filtering, renaming, validation, or versioning",
@@ -29,6 +30,7 @@ export const defaultChecks: readonly StupifyCheck[] = [
     id: checkId("unnecessary_complexity"),
     name: "Unnecessary complexity",
     question: "Did the change add structure without buying clarity?",
+    why: "Extra indirection can hide simple decisions and make the code feel more designed than understood.",
     lookFor: [
       "helper, wrapper, service, layer, or extra file around simple logic without reuse",
     ],
@@ -69,6 +71,7 @@ Prefer no match over a weak match.`,
     id: checkId("fake_precision_windowing"),
     name: "Fake precision windowing",
     question: "Did the change add fake precision around model context?",
+    why: "Precise-looking bookkeeping can create confidence without improving the actual behavior.",
     lookFor: [
       "precise-looking counts, budgets, ratios, reports, or batching fields without useful behavior",
     ],
@@ -81,6 +84,7 @@ Prefer no match over a weak match.`,
     id: checkId("coauthored_slop"),
     name: "Coauthored slop",
     question: "Does author metadata contain co-author text?",
+    why: "Careless metadata is a cheap signal that the change may not have been reviewed with intent.",
     lookFor: [
       "author signal contains coauhtoried, coauthored, or co-authored text",
     ],
@@ -92,6 +96,7 @@ Prefer no match over a weak match.`,
     id: checkId("mega_file"),
     name: "Mega file",
     question: "Is a touched non-config file over 1000 LOC?",
+    why: "Large files make judgment harder by concentrating unrelated decisions in one place.",
     lookFor: [
       "touched non-config source file over 1000 LOC",
     ],
@@ -103,6 +108,7 @@ Prefer no match over a weak match.`,
     id: checkId("over_commenting"),
     name: "Over commenting",
     question: "Did the change add noisy comments?",
+    why: "Narrative comments can make routine code look deliberate without clarifying the underlying tradeoff.",
     lookFor: [
       "comments restate obvious code or narrate simple logic",
     ],
@@ -130,6 +136,7 @@ Prefer no match over a weak match.`,
     id: checkId("lint_bypass"),
     name: "Lint bypass",
     question: "Did the change bypass lint or type rules?",
+    why: "Unexplained suppressions remove useful feedback exactly where a change needs more scrutiny.",
     lookFor: [
       "adds suppressions, any, broad casts, or weakens lint/typecheck config",
     ],
@@ -153,6 +160,7 @@ Prefer no match over a weak match.`,
     id: checkId("inconsistent_patterns"),
     name: "Inconsistent patterns",
     question: "Does the change clash with nearby patterns?",
+    why: "Pattern drift can signal that a change followed generic suggestions instead of local codebase judgment.",
     lookFor: [
       "same job uses different naming, errors, state, imports, or layout than nearby files",
     ],
@@ -165,6 +173,7 @@ Prefer no match over a weak match.`,
     id: checkId("reinvented_utils"),
     name: "Reinvented utils",
     question: "Did the change recreate an existing utility?",
+    why: "Generic helper reinvention can be a sign that the change optimized for plausible code over local reuse.",
     lookFor: [
       "new helper duplicates local utility or standard library behavior",
     ],
@@ -189,6 +198,7 @@ Prefer no match over a weak match.`,
     id: checkId("operator_style_mismatch"),
     name: "Operator style mismatch",
     question: "Does the change read unlike the surrounding code?",
+    why: "Style mismatch can reveal generic generated code that was not reconciled with nearby conventions.",
     lookFor: [
       "generic or template-like names, abstractions, comments, or control flow clash with local style",
     ],

package/src/constants.ts

@@ -1,4 +1,4 @@
-export const VERSION = "0.0.7";
+export const VERSION = "0.0.8";
 import type { ModelConfig, ModelId } from "./types.ts";
 
 export const DEFAULT_MODEL_ID: ModelId = "gemma-4-e2b";

package/src/prompts.ts

@@ -64,6 +64,7 @@ ${input.pack.text || "(none)"}`;
 
 function formatSearchPattern(check: StupifyCheck): string {
   return `Pattern: ${check.id} (${check.name})
+Why this matters: ${check.why}
 Question: ${check.searchPrompt ?? check.question}
 Look for:
 ${check.lookFor.map((signal) => `- ${signal}`).join("\n")}
@@ -92,6 +93,7 @@ function patternForContext(context: SemContext, patterns: readonly StupifyCheck[
     id: context.checkId,
     name: context.checkId,
     question: `Does this target match ${context.checkId}?`,
+    why: "This pattern may indicate judgment-offload.",
     lookFor: [],
     ignoreWhen: [],
   };

package/src/render.ts

@@ -34,7 +34,8 @@ No judgment-offload signals found.`;
   return `🧙 stupify 🪄
 Possible judgment-offload detected:
 ${run.matches.map((match, index) => `${index + 1}. ${match.patternId}
-   ${match.reason}
+   Why: ${match.checkWhy ?? "This pattern may indicate judgment-offload."}
+   Match: ${match.reason}
    Proof: ${match.proof}`).join("\n")}
 Search mode is warn-only.`;
 }

package/src/stupify.ts

@@ -20,7 +20,7 @@ import {
 } from "./search-profile.ts";
 import { semChangeSetForCommand } from "./sem-provider.ts";
 import { createTracer } from "./trace.ts";
-import type { SearchCommand, SearchProfile, SearchRunJson, SemContext, SemContextPack, StupifyCheck } from "./types.ts";
+import type { SearchCommand, SearchMatch, SearchProfile, SearchRunJson, SemContext, SemContextPack, StupifyCheck } from "./types.ts";
 
 export async function main(argv = process.argv.slice(2)): Promise<number> {
   const startedAt = Date.now();
@@ -225,7 +225,7 @@ export async function runSearchCommand(command: SearchCommand, startedAt: number
         { count: (v) => v.length },
       );
       modelCalls += 1;
-      matches.push(...value);
+      matches.push(...withCheckWhy(value, checks));
     }
     const uniqueMatches = dedupeMatches(matches);
 
@@ -270,6 +270,14 @@ function dedupeMatches<T extends { targetId: string; patternId: string; proof: s
   });
 }
 
+function withCheckWhy(matches: readonly SearchMatch[], checks: readonly StupifyCheck[]): readonly SearchMatch[] {
+  const checksById = new Map(checks.map((check) => [check.id, check]));
+  return matches.map((match) => ({
+    ...match,
+    checkWhy: checksById.get(match.patternId)?.why,
+  }));
+}
+
 type SearchBatch = Readonly<{
   contexts: readonly SemContext[];
   pack: SemContextPack;

package/src/types.ts

@@ -51,6 +51,7 @@ export type StupifyCheck = Readonly<{
   id: CheckId;
   name: string;
   question: string;
+  why: string;
   lookFor: readonly string[];
   ignoreWhen: readonly string[];
   enabledByDefault?: boolean;
@@ -192,6 +193,7 @@ export type SearchProfile = Readonly<{
 export type SearchMatch = Readonly<{
   targetId: string;
   patternId: CheckId;
+  checkWhy?: string;
   reason: string;
   proof: string;
 }>;