@amrishkhan05/frankly 0.1.0

package/hooks/hooks.json

@@ -0,0 +1,13 @@
+{
+  "description": "Run one local Red Ink Review when Claude finishes a task.",
+  "hooks": {
+    "Stop": [{
+      "hooks": [{
+        "type": "command",
+        "command": "node",
+        "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/run.cjs", "checkpoint", "${CLAUDE_PLUGIN_DATA}"],
+        "timeout": 60
+      }]
+    }]
+  }
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@amrishkhan05/frankly",
+  "version": "0.1.0",
+  "description": "Change intelligence for AI coding agents. Every changed line should earn its place.",
+  "type": "module",
+  "bin": {
+    "frankly": "dist/integrations/cli/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/integrations/cli/index.ts",
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "mcp": "tsx src/integrations/mcp/index.ts",
+    "review": "tsx src/integrations/cli/index.ts review",
+    "verify": "tsx src/integrations/cli/index.ts verify",
+    "demo": "tsx src/integrations/cli/demo.ts",
+    "benchmark": "tsx benchmarks/run.ts",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "vitest": "^4.1.11"
+  },
+  "files": [
+    "dist",
+    "src",
+    "scripts",
+    ".claude-plugin",
+    ".github",
+    ".mcp.json",
+    "hooks",
+    "skills",
+    "commands",
+    "fixtures",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ai",
+    "code-review",
+    "mcp",
+    "claude-code",
+    "change-intelligence"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amrishkhan05/frankly.git"
+  },
+  "homepage": "https://github.com/amrishkhan05/frankly#readme",
+  "bugs": {
+    "url": "https://github.com/amrishkhan05/frankly/issues"
+  },
+  "license": "MIT",
+  "author": "Amrish Khan <amrishkhan05@gmail.com>",
+  "main": "index.js",
+  "directories": {
+    "doc": "docs",
+    "example": "examples"
+  }
+}

package/scripts/run.cjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+const { execFileSync, spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const root = path.resolve(__dirname, "..");
+const mode = process.argv[2] || "mcp";
+const data = process.env.FRANKLY_PLUGIN_DATA || (mode === "checkpoint" ? process.argv[3] : undefined) || root;
+
+if (data !== root) {
+  const marker = path.join(data, ".frankly-version");
+  const version = require(path.join(root, "package.json")).version;
+  if (!fs.existsSync(marker) || fs.readFileSync(marker, "utf8") !== version) {
+    fs.mkdirSync(data, { recursive: true });
+    fs.cpSync(path.join(root, "src"), path.join(data, "src"), { recursive: true });
+    fs.copyFileSync(path.join(root, "package.json"), path.join(data, "package.json"));
+    execFileSync("npm", ["install", "--omit=dev", "--ignore-scripts", "--no-audit", "--no-fund"], { cwd: data, stdio: "inherit" });
+    fs.writeFileSync(marker, version);
+  }
+}
+
+const entry = mode === "checkpoint"
+  ? "src/integrations/claude/checkpoint.ts"
+  : mode === "mcp"
+    ? "src/integrations/mcp/index.ts"
+    : "src/integrations/cli/index.ts";
+const tsx = path.join(data, "node_modules", ".bin", process.platform === "win32" ? "tsx.cmd" : "tsx");
+const result = spawnSync(tsx, [path.join(data, entry), ...(mode === "checkpoint" || mode === "mcp" ? [] : process.argv.slice(2))], {
+  cwd: process.cwd(),
+  stdio: "inherit",
+});
+process.exit(result.status ?? 1);

package/skills/frankly/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: frankly
+description: Plan, review, minimize, and verify code changes with local repository evidence.
+---
+
+# Frankly
+
+Before editing, call `plan_change` with the user's task when scope is uncertain.
+
+At a meaningful completion checkpoint, call `analyze_change`. If its verdict warrants correction, follow the single correction instruction returned by `minimize_change`, preserving requested behavior and safety checks. Then call `verify_change` once with any tests actually executed.
+
+Never describe predicted tests as executed. Never repeat a correction pass.

package/src/analysis/change-classifier.ts

@@ -0,0 +1,285 @@
+/**
+ * Change analysis and classification
+ * Determines necessity and classification of changed symbols
+ */
+
+import type {
+    ChangedFile,
+    ChangedSymbol,
+    ChangeClassification,
+    Evidence,
+} from "../core/models.js";
+import { countDiffLines, type FileDiff } from "../git/repository.js";
+import type { ExtractedSymbol } from "../graph/symbols.js";
+
+export interface ChangeAnalysisInput {
+    task: string;
+    files: FileDiff[];
+    symbols: Map<string, ExtractedSymbol[]>;
+}
+
+export interface ClassifiedChange {
+    symbol: ChangedSymbol | ChangedFile;
+    classification: ChangeClassification;
+    confidence: "high" | "medium" | "low";
+    justification: string;
+    evidence: Evidence[];
+}
+
+export class ChangeAnalyzer {
+    /**
+     * Classify all changes
+     */
+    classifyChanges(input: ChangeAnalysisInput): ClassifiedChange[] {
+        const taskKeywords = this.extractTaskKeywords(input.task);
+        const classifications: ClassifiedChange[] = [];
+
+        // Classify files
+        for (const file of input.files) {
+            const classification = this.classifyFile(file, taskKeywords);
+            classifications.push(classification);
+
+            for (const symbol of (input.symbols.get(file.path) || []).filter((item) =>
+                file.status === "added" || file.hunks.some((hunk) => rangesOverlap(item.lineRange, [hunk.newStart, hunk.newStart + Math.max(0, hunk.newLines - 1)])),
+            )) {
+                const changed = this.toChangedSymbol(file, symbol);
+                const matched = taskKeywords.some((keyword) => changed.name.toLowerCase().includes(keyword));
+                classifications.push({
+                    symbol: changed,
+                    classification: this.isTestFile(file.path) ? "TEST" : matched ? "REQUIRED" : "SUPPORTING",
+                    confidence: matched ? "high" : "medium",
+                    justification: matched ? "Changed symbol matches task intent" : "Symbol is inside a changed hunk",
+                    evidence: [{
+                        type: matched ? "TASK_MATCH" : "DIFF_DEPENDENT",
+                        confidence: matched ? "high" : "medium",
+                        explanation: matched ? `Symbol ${changed.name} matches task keywords` : `Symbol ${changed.name} overlaps a changed hunk`,
+                        reference: changed.id,
+                    }],
+                });
+            }
+        }
+
+        return classifications;
+    }
+
+    /**
+     * Extract keywords from task description
+     */
+    public extractTaskKeywords(task: string): string[] {
+        return task
+            .toLowerCase()
+            .replace(/[^a-z0-9\s]/g, " ")
+            .split(/\s+/)
+            .filter((word) => word.length > 2 && !this.isCommonWord(word));
+    }
+
+    /**
+     * Normalize a task into a compact intent string.
+     */
+    public normalizeTaskIntent(task: string): string {
+        const keywords = this.extractTaskKeywords(task);
+        return keywords.join(" ") || task.trim();
+    }
+
+    /**
+     * Check if word is a common English word
+     */
+    private isCommonWord(word: string): boolean {
+        const common = new Set([
+            "the",
+            "and",
+            "for",
+            "with",
+            "that",
+            "this",
+            "from",
+            "have",
+            "will",
+            "when",
+            "can",
+            "are",
+            "all",
+            "each",
+            "where",
+            "should",
+            "add",
+            "fix",
+            "update",
+            "change",
+            "modify",
+            "remove",
+            "create",
+        ]);
+        return common.has(word);
+    }
+
+    /**
+     * Classify a file change
+     */
+    private classifyFile(file: FileDiff, taskKeywords: string[]): ClassifiedChange {
+        const evidence: Evidence[] = [];
+
+        // Check if file matches task keywords
+    const pathMatch = this.calculatePathMatchScore(`${file.path}\n${file.hunks.map((hunk) => hunk.content).join("\n")}`, taskKeywords);
+    if (pathMatch > 0) {
+            evidence.push({
+                type: "TASK_MATCH",
+                confidence: "high",
+                explanation: `File path matches task keywords: ${file.path}`,
+            });
+        }
+
+        // Calculate additions/deletions/changes
+    const { additions, deletions } = countDiffLines(file);
+        const changes = file.hunks.length;
+
+        let classification: ChangeClassification = "UNEXPLAINED";
+        let confidence: "high" | "medium" | "low" = "low";
+        let justification = "File change appears unrelated to task";
+
+        if (this.isGeneratedFile(file.path)) {
+            classification = "GENERATED";
+            confidence = "high";
+            justification = "Generated artifact changed with the patch";
+        } else if (file.status === "deleted") {
+            classification = "UNEXPLAINED";
+            confidence = "high";
+            justification = "Deleted file - requires explanation";
+        } else if (file.status === "added") {
+      if (pathMatch > 0) {
+                classification = "SUPPORTING";
+                confidence = "high";
+                justification = "New file related to task";
+            } else {
+                classification = "SUSPICIOUS";
+                confidence = "medium";
+                justification = "New file with unclear relationship to task";
+            }
+        } else if (file.status === "modified") {
+      if (pathMatch > 0) {
+                classification = "REQUIRED";
+                confidence = "high";
+                justification = "File directly related to task";
+            } else if (this.isTestFile(file.path)) {
+                classification = "TEST";
+                confidence = "medium";
+                justification = "Test file modification";
+            } else if (this.isConfigFile(file.path)) {
+                classification = "SUPPORTING";
+                confidence = "medium";
+                justification = "Configuration file change";
+            } else {
+                classification = "SUSPICIOUS";
+                confidence = "low";
+                justification = "File change weakly related to task";
+            }
+        } else if (file.status === "renamed") {
+            classification = "SUSPICIOUS";
+            confidence = "medium";
+            justification = "File rename requires explanation";
+        }
+
+        return {
+            symbol: {
+                path: file.path,
+                changeType: file.status,
+                additions,
+                deletions,
+                changes,
+                symbols: [],
+            },
+            classification,
+            confidence,
+            justification,
+            evidence,
+        };
+    }
+
+    private toChangedSymbol(file: FileDiff, symbol: ExtractedSymbol): ChangedSymbol {
+        return {
+            id: `${file.path}:${symbol.name}:${symbol.lineRange[0]}`,
+            name: symbol.name,
+            type: symbol.type,
+            filePath: file.path,
+            lineRange: symbol.lineRange,
+            changeType: file.status,
+            visibility: symbol.visibility,
+            isExported: symbol.isExported,
+            callers: [],
+            callees: [],
+            implementations: [],
+            interfaces: [],
+            referencedContracts: [],
+            relatedTests: [],
+            evidence: [],
+        };
+    }
+
+    /**
+     * Calculate how much a file path matches task keywords
+     */
+    private calculatePathMatchScore(filePath: string, keywords: string[]): number {
+        if (keywords.length === 0) return 0;
+
+        const pathParts = filePath.toLowerCase().split(/[\\/\.]/);
+        let matches = 0;
+
+        for (const keyword of keywords) {
+            if (pathParts.some((part) => part.includes(keyword))) {
+                matches++;
+            }
+        }
+
+        return matches / keywords.length;
+    }
+
+    /**
+     * Check if file is a test file
+     */
+    private isTestFile(filePath: string): boolean {
+        return /\.(test|spec)\.(ts|js|tsx|jsx)$/.test(filePath) || filePath.includes("__tests__");
+    }
+
+    /**
+     * Check if file is a config file
+     */
+    private isConfigFile(filePath: string): boolean {
+        return (
+            /\.(config|rc)\.(ts|js|json)$/.test(filePath) ||
+            /^\./.test(filePath) ||
+            ["package.json", "tsconfig.json", "jest.config.js"].includes(filePath.split("/").pop() || "")
+        );
+    }
+
+    private isGeneratedFile(filePath: string): boolean {
+        return /(?:^|\/)(?:dist|build|generated)\//.test(filePath) || /(?:-lock\.json|pnpm-lock\.yaml|yarn\.lock|\.snap)$/.test(filePath);
+    }
+
+    /**
+     * Detect scope drift percentage
+     */
+    detectScopeDrift(
+        classifications: ClassifiedChange[],
+        totalChanges: number,
+    ): number {
+        const suspiciousCount = classifications.filter((c) => c.classification === "SUSPICIOUS").length;
+        return suspiciousCount / Math.max(totalChanges, 1);
+    }
+
+    /**
+     * Detect refactor contamination
+     */
+    detectRefactorContamination(classifications: ClassifiedChange[]): string[] {
+        return classifications
+            .filter((c) => c.classification === "REFACTOR")
+            .map((c) => (typeof c.symbol === "object" && "path" in c.symbol) ? c.symbol.path : "unknown");
+    }
+}
+
+function rangesOverlap(left: [number, number], right: [number, number]): boolean {
+    return left[0] <= right[1] && right[0] <= left[1];
+}
+
+export function createChangeAnalyzer(): ChangeAnalyzer {
+    return new ChangeAnalyzer();
+}

package/src/analysis/repository-intelligence.ts

@@ -0,0 +1,236 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as ts from "typescript";
+import type {
+  BehavioralChangeType,
+  ChangedSymbol,
+  ContractChange,
+  CorrectionPlan,
+  Evidence,
+  ExecutedTest,
+  Finding,
+  PredictedTest,
+} from "../core/models.js";
+import type { FileDiff } from "../git/repository.js";
+
+export interface RepositoryIntelligence {
+  directCallers: string[];
+  transitiveCallers: string[];
+  packages: string[];
+  predictedTests: PredictedTest[];
+  contracts: ContractChange[];
+  behavioralChanges: BehavioralChangeType[];
+  reuseCandidates: string[];
+  findings: Finding[];
+  correction?: CorrectionPlan;
+}
+
+const SOURCE_RE = /\.[cm]?[jt]sx?$/;
+const TEST_RE = /(?:^|\/)(?:__tests__\/.*|.*\.(?:test|spec))\.[cm]?[jt]sx?$/;
+const SKIP = new Set([".git", "node_modules", "dist", "build", "coverage", ".next"]);
+
+export function inspectRepository(
+  root: string,
+  taskKeywords: string[],
+  diffs: FileDiff[],
+  changedSymbols: ChangedSymbol[],
+  executedTests: ExecutedTest[] = [],
+): RepositoryIntelligence {
+  const sourceFiles = walk(root).filter((file) => SOURCE_RE.test(file));
+  const relativeFiles = sourceFiles.map((file) => path.relative(root, file).split(path.sep).join("/"));
+  const changed = new Set(diffs.map((file) => file.path));
+  const imports = new Map<string, string[]>();
+  const contents = new Map<string, string>();
+
+  for (const relative of relativeFiles) {
+    const content = fs.readFileSync(path.join(root, relative), "utf8");
+    contents.set(relative, content);
+    imports.set(relative, extractImports(content).map((specifier) => resolveImport(relative, specifier, relativeFiles)).filter(Boolean) as string[]);
+  }
+
+  const directCallers = relativeFiles.filter((file) => imports.get(file)?.some((target) => changed.has(target)));
+  const transitive = new Set(directCallers);
+  let frontier = [...directCallers];
+  while (frontier.length) {
+    const targets = new Set(frontier);
+    frontier = relativeFiles.filter((file) => !transitive.has(file) && imports.get(file)?.some((target) => targets.has(target)));
+    frontier.forEach((file) => transitive.add(file));
+  }
+
+  const predictedTests = relativeFiles.filter((file) => TEST_RE.test(file)).flatMap((file): PredictedTest[] => {
+    const body = contents.get(file) || "";
+    const related = directCallers.includes(file) || imports.get(file)?.some((target) => changed.has(target));
+    const mentionsSymbol = changedSymbols.some((symbol) => body.includes(symbol.name.split(".").pop() || symbol.name));
+    const sameStem = diffs.some((diff) => path.basename(file).includes(path.basename(diff.path).replace(/\.[^.]+$/, "")));
+    if (!related && !mentionsSymbol && !sameStem) return [];
+    const status = related || mentionsSymbol ? "LIKELY_AFFECTED" : "POSSIBLY_AFFECTED";
+    return [{
+      path: file,
+      name: path.basename(file),
+      status,
+      evidence: [{
+        type: related ? "IMPORT_DEPENDENCY" : "TEST_REFERENCE",
+        confidence: related ? "high" : "medium",
+        explanation: related ? "Test imports a changed module" : "Test name or contents reference a changed symbol",
+        reference: file,
+      }],
+    }];
+  });
+
+  const contracts = changedSymbols.filter((symbol) => symbol.isExported).map((symbol): ContractChange => ({
+    type: symbol.changeType === "added" ? "ADDED" : symbol.changeType === "deleted" ? "REMOVED" : "CHANGED",
+    location: `${symbol.filePath}:${symbol.lineRange[0]} ${symbol.name}`,
+    severity: symbol.changeType === "added" ? "compatible" : "potentially-breaking",
+    confidence: symbol.changeType === "added" ? "high" : "medium",
+    affectedCallers: directCallers.filter((file) => imports.get(file)?.includes(symbol.filePath)),
+  }));
+
+  const diffText = diffs.flatMap((file) => file.hunks.map((hunk) => hunk.content)).join("\n").toLowerCase();
+  const behavioralChanges = behaviorFrom(diffText, diffs);
+  const reuseCandidates = findReuseCandidates(taskKeywords, changed, contents, root);
+  const findings: Finding[] = [];
+
+  if (reuseCandidates[0]) findings.push(finding(
+    "reuse-candidate", "warning", "medium", "Existing code may be reusable",
+    `${reuseCandidates[0]} contains task-related symbols or text and is unchanged by this patch.`, [reuseCandidates[0]],
+    "Inspect this existing mechanism before keeping a parallel implementation.",
+    { type: "EXISTING_UTILITY", confidence: "medium", explanation: "Unchanged repository code matches task intent", reference: reuseCandidates[0] },
+  ));
+
+  for (const symbol of changedSymbols.filter((item) => item.changeType === "added" && ["interface", "class"].includes(item.type))) {
+    const uses = [...contents.values()].reduce((count, body) => count + occurrences(body, symbol.name), 0);
+    if (uses <= 2) findings.push(finding(
+      "unnecessary-abstraction",
+      "warning",
+      "medium",
+      "Possible unnecessary abstraction",
+      `${symbol.type} ${symbol.name} has no evidence of reuse outside its declaration.`,
+      [symbol.id],
+      "Keep it local unless another consumer requires the abstraction.",
+      { type: "SYMBOL_REFERENCE", confidence: "medium", explanation: `Found ${Math.max(0, uses - 1)} use(s) outside the declaration`, reference: symbol.id },
+    ));
+  }
+
+  for (const file of diffs.filter((item) => item.path === "package.json" && item.status === "modified")) {
+    const additions = file.hunks.flatMap((hunk) => hunk.content.split("\n")).filter((line) => /^\+\s*"[^"]+"\s*:/.test(line));
+    if (additions.length) findings.push(finding(
+      "dependency-addition", "warning", "high", "Dependency addition needs justification",
+      `package.json adds ${additions.length} dependency entry or entries.`, [file.path],
+      "Use the runtime or an existing dependency unless the task requires this package.",
+      { type: "DEPENDENCY_USAGE", confidence: "high", explanation: additions.join(", "), reference: file.path },
+    ));
+  }
+
+  if (behavioralChanges.some((type) => type !== "TEST_ONLY" && type !== "REFACTOR_ONLY") && predictedTests.length === 0) {
+    findings.push(finding(
+      "missing-regression-test", "warning", "medium", "Missing regression coverage",
+      `Behavioral change detected (${behavioralChanges.join(", ")}) but no related test was found.`, [],
+      "Add one regression test for the changed behavior.",
+      { type: "TEST_REFERENCE", confidence: "medium", explanation: "No test imports or references the changed code" },
+    ));
+  }
+
+  const packages = new Set([...changed, ...directCallers].map((file) => packageFor(root, file)).filter(Boolean) as string[]);
+  const removalPaths = diffs.filter((file) =>
+    !taskKeywords.some((word) => file.path.toLowerCase().includes(word))
+    && !TEST_RE.test(file.path)
+    && !imports.get(file.path)?.some((target) => changed.has(target)),
+  ).map((file) => file.path);
+  const evidence: Evidence[] = removalPaths.map((file) => ({ type: "TASK_MATCH", confidence: "medium", explanation: "No task keyword matched this path", reference: file }));
+  const correction = findings.length || removalPaths.length ? {
+    pass: 1,
+    removals: removalPaths,
+    simplifications: findings.filter((item) => item.id.startsWith("unnecessary-abstraction")).map((item) => ({ symbol: item.affectedSymbols[0], suggestion: item.recommendation || "Inline it" })),
+    evidence,
+    instruction: correctionInstruction([...findings, ...removalPaths.map((file) => finding("scope", "warning", "medium", "Weak task evidence", file, [file], "Remove or justify it", evidence.find((item) => item.reference === file)!))]),
+  } satisfies CorrectionPlan : undefined;
+
+  return {
+    directCallers,
+    transitiveCallers: [...transitive].filter((file) => !directCallers.includes(file)),
+    packages: [...packages],
+    predictedTests,
+    contracts,
+    behavioralChanges,
+    reuseCandidates,
+    findings,
+    correction,
+  };
+}
+
+function walk(root: string): string[] {
+  const files: string[] = [];
+  const visit = (directory: string) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (SKIP.has(entry.name)) continue;
+      const full = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(full);
+      else if (entry.isFile()) files.push(full);
+    }
+  };
+  visit(root);
+  return files;
+}
+
+function extractImports(content: string): string[] {
+  const source = ts.createSourceFile("file.ts", content, ts.ScriptTarget.Latest, true);
+  return source.statements.flatMap((statement): string[] => {
+    if ((ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) && statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)) return [statement.moduleSpecifier.text];
+    return [];
+  });
+}
+
+function resolveImport(from: string, specifier: string, files: string[]): string | undefined {
+  if (!specifier.startsWith(".")) return undefined;
+  const base = path.posix.normalize(path.posix.join(path.posix.dirname(from), specifier)).replace(/\.js$/, "");
+  return files.find((file) => file.replace(/\.[^.]+$/, "") === base || file.replace(/\/index\.[^.]+$/, "") === base);
+}
+
+function findReuseCandidates(keywords: string[], changed: Set<string>, contents: Map<string, string>, root: string): string[] {
+  const scored: Array<[string, number]> = [];
+  for (const [file, body] of contents) {
+    if (changed.has(file) || TEST_RE.test(file)) continue;
+    const lower = `${file}\n${body}`.toLowerCase();
+    const pathScore = keywords.filter((word) => file.toLowerCase().includes(word)).length;
+    const score = pathScore * 10 + keywords.filter((word) => lower.includes(word)).length;
+    if (score) scored.push([file, score]);
+  }
+  return scored.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 5).map(([file]) => path.relative(root, path.join(root, file)));
+}
+
+function behaviorFrom(text: string, diffs: FileDiff[]): BehavioralChangeType[] {
+  const found = new Set<BehavioralChangeType>();
+  const rules: Array<[RegExp, BehavioralChangeType]> = [
+    [/throw|catch|error/, "ERROR_HANDLING"], [/retry|429|backoff/, "RETRY"], [/cache|memo/, "CACHE"],
+    [/auth|permission|role/, "AUTHORIZATION"], [/insert|update|delete|save|write/, "STATE_MUTATION"],
+    [/route|request|response|status/, "API_BEHAVIOR"], [/env|config/, "CONFIGURATION"], [/promise|async|await|lock/, "CONCURRENCY"],
+  ];
+  rules.forEach(([pattern, type]) => { if (pattern.test(text)) found.add(type); });
+  if (diffs.every((file) => TEST_RE.test(file.path))) found.add("TEST_ONLY");
+  return [...found];
+}
+
+function packageFor(root: string, file: string): string | undefined {
+  let directory = path.dirname(path.join(root, file));
+  while (directory.startsWith(root)) {
+    const manifest = path.join(directory, "package.json");
+    if (fs.existsSync(manifest)) {
+      try { return JSON.parse(fs.readFileSync(manifest, "utf8")).name || path.relative(root, directory) || "root"; } catch { return path.relative(root, directory) || "root"; }
+    }
+    if (directory === root) break;
+    directory = path.dirname(directory);
+  }
+  return undefined;
+}
+
+function occurrences(body: string, word: string): number {
+  return body.match(new RegExp(`\\b${word.replace(/[.*+?^${}()|[\\]\\]/g, "\\$&")}\\b`, "g"))?.length || 0;
+}
+
+function finding(id: string, severity: "error" | "warning" | "info", confidence: "high" | "medium" | "low", title: string, description: string, affectedSymbols: string[], recommendation: string, evidence: Evidence): Finding {
+  return { id: `${id}-${affectedSymbols[0] || "change"}`, severity, confidence, title, description, affectedSymbols, recommendation, evidence: [evidence], autoCorrectible: severity !== "error" };
+}
+
+function correctionInstruction(findings: Finding[]): string {
+  return `Revisit the current patch once. Preserve requested behavior and all validation, security, accessibility, data integrity, error handling, and regression coverage. Do not add functionality. Resolve or justify these red marks:\n${findings.map((item) => `- ${item.title}: ${item.description}`).join("\n")}\nReturn the smallest safe patch that satisfies the task.`;
+}