@geminixiang/pi-simplify 0.0.10 → 0.1.0

package/CHANGELOG.md

@@ -6,6 +6,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.1.0] - 2026-06-03
+
+### Added
+
+- Add `/code-smell` command: finds structural problems with programmatic checks (debug remnants, commented-out code, duplication, complex functions) plus agent review across complexity, duplication, coupling, state, errors, performance, and maintainability smell families.
+- Programmatic scanner runs deterministically before agent review; findings are verified by reading files before surfacing them.
+- Interactive findings selector: ranked by severity, auto-selects high-severity / high-confidence items, shows cause-effect chain inline.
+
+### Fixed
+
+- Skip redundant `## Scope` section in the agent prompt when scanning the repository root.
+
+### Changed
+
+- Reorganise source into `src/simplify/` and `src/code-smell/` subdirectories.
+
+## [0.0.11] - 2026-06-03
+
+### Changed
+
+- Add thin-wrapper review heuristics so `/simplify` flags rename-only wrappers, pass-through factories, single-call-site helpers, duplicated write APIs, and test-only exports only when they create real maintenance cost.
+
 ## [0.0.10] - 2026-05-30
 
 ### Changed

package/README.md

@@ -16,6 +16,8 @@ After implementing a feature, your code often accumulates:
 
 `/simplify` finds these and removes them.
 
+`/code-smell` goes deeper — it runs programmatic checks plus agent review to surface structural problems like coupling, error handling gaps, and performance issues.
+
 ## Installation
 
 ```sh
@@ -24,6 +26,32 @@ pi install npm:@geminixiang/pi-simplify
 
 ## Usage
 
+### Code Smell Analysis
+
+```
+/code-smell
+```
+
+Opens a scope selector. Choose to scan the repository or specific paths.
+
+Runs programmatic checks (debug remnants, commented-out code, duplication, complex functions) then agent review across seven smell families:
+
+- **Complexity** - long functions, deep nesting, mixed responsibilities
+- **Duplication** - copy-paste blocks, repeated condition chains
+- **Coupling** - cross-layer reach-through, boundary violations
+- **State** - redundant derived state, multiple sources of truth
+- **Errors** - swallowed errors, empty catches, inconsistent mapping
+- **Performance** - N+1 loops, sequential independent awaits
+- **Maintainability** - debug remnants, TODO/HACK markers, stringly-typed constants
+
+Findings are ranked by severity. Select which to fix and the agent applies small, behavior-preserving cleanups.
+
+```
+/code-smell src lib
+```
+
+Scans specific paths directly.
+
 ### Full Simplify
 
 ```
@@ -53,6 +81,15 @@ Analyzes the specified folders/files as a snapshot (not a diff), even when there
 /simplify focus on removing debug code
 ```
 
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `/simplify` | Delete excess after a feature: dead code, debug remnants, thin wrappers |
+| `/simplify folder <paths>` | Same as above but snapshot mode (no git diff needed) |
+| `/code-smell` | Find structural problems: coupling, complexity, error handling, performance |
+| `/code-smell <paths>` | Scan specific paths for code smells |
+
 ## Comparison with pi-review
 
 |              | pi-review                   | pi-simplify           |

package/index.ts

@@ -1,16 +1,15 @@
 /**
  * pi-simplify: Code Review & Cleanup Extension for pi
  *
- * Reviews changed code for reuse, quality, and efficiency:
- * - Reuse: replace newly-written code with existing utilities
- * - Quality: dead code, debug remnants, commented-out code, over-engineering, duplicate logic
- * - Efficiency: redundant work, missed concurrency, hot-path bloat, memory leaks
+ * /simplify — reviews changed code for reuse, quality, and efficiency
+ * /code-smell — finds structural problems with programmatic checks and agent review
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-import { registerSimplifyWorkflow } from "./workflow.js";
+import { registerCodeSmellWorkflow } from "./src/code-smell/workflow.js";
+import { registerSimplifyWorkflow } from "./src/simplify/workflow.js";
 
 export default function simplifyExtension(pi: ExtensionAPI) {
   registerSimplifyWorkflow(pi);
+  registerCodeSmellWorkflow(pi);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geminixiang/pi-simplify",
-  "version": "0.0.10",
+  "version": "0.1.0",
   "description": "Simplify: Review changed code for reuse, quality, and efficiency",
   "keywords": [
     "pi-package"

package/src/code-smell/checks.ts

@@ -0,0 +1,210 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+
+import type { ProgrammaticCheck, SmellCategory, SmellSeverity } from "./types.js";
+
+const DEFAULT_IGNORES = new Set([
+  ".git",
+  "node_modules",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".turbo",
+  ".cache",
+]);
+
+const TEXT_EXTENSIONS = new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".go",
+  ".rs",
+  ".java",
+  ".kt",
+  ".rb",
+  ".php",
+  ".cs",
+  ".swift",
+]);
+
+type ScanOptions = {
+  cwd: string;
+  paths: string[];
+  maxFiles?: number;
+};
+
+type SourceFile = {
+  absolutePath: string;
+  relativePath: string;
+  text: string;
+  lines: string[];
+};
+
+async function collectFiles(root: string, target: string, out: string[], maxFiles: number) {
+  if (out.length >= maxFiles) return;
+  const absolute = path.resolve(root, target);
+  const info = await stat(absolute).catch(() => null);
+  if (!info) return;
+
+  if (info.isFile()) {
+    if (TEXT_EXTENSIONS.has(path.extname(absolute))) out.push(absolute);
+    return;
+  }
+
+  if (!info.isDirectory()) return;
+  const entries = await readdir(absolute, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    if (out.length >= maxFiles) return;
+    if (DEFAULT_IGNORES.has(entry.name)) continue;
+    await collectFiles(root, path.join(target, entry.name), out, maxFiles);
+  }
+}
+
+function lineRange(start: number, end?: number) {
+  return end && end !== start ? `${start}-${end}` : String(start);
+}
+
+function push(
+  findings: ProgrammaticCheck[],
+  args: Omit<ProgrammaticCheck, "severity" | "category"> & {
+    category: SmellCategory;
+    severity: SmellSeverity;
+  },
+) {
+  findings.push(args);
+}
+
+function scanFile(file: SourceFile): ProgrammaticCheck[] {
+  const findings: ProgrammaticCheck[] = [];
+  const counts = new Map<string, number[]>();
+  let functionStart: number | null = null;
+  let functionBraceDepth = 0;
+  let currentFunctionComplexity = 0;
+
+  file.lines.forEach((raw, index) => {
+    const lineNo = index + 1;
+    const line = raw.trim();
+    const normalized = line.replace(/\s+/g, " ");
+
+    if (normalized.length > 20 && !normalized.startsWith("//") && !normalized.startsWith("*")) {
+      const existing = counts.get(normalized) ?? [];
+      existing.push(lineNo);
+      counts.set(normalized, existing);
+    }
+
+    if (/\b(console\.(log|debug|warn|error)|debugger)\b/.test(line)) {
+      push(findings, {
+        id: "debug-remnant",
+        title: "Debug remnant",
+        category: "maintainability",
+        severity: line.includes("debugger") ? "high" : "medium",
+        file: file.relativePath,
+        lines: String(lineNo),
+        evidence: raw.trim(),
+        recommendation:
+          "Remove temporary logging/debug statements or replace with the project's structured logger if this is intentional.",
+      });
+    }
+
+    if (/^\/\/\s*(if|for|while|return|const|let|var|function|class|import|export)\b/.test(line)) {
+      push(findings, {
+        id: "commented-out-code",
+        title: "Commented-out code",
+        category: "maintainability",
+        severity: "low",
+        file: file.relativePath,
+        lines: String(lineNo),
+        evidence: raw.trim(),
+        recommendation:
+          "Delete stale commented code; git history is the source of old implementations.",
+      });
+    }
+
+    if (/\b(any|TODO|FIXME|HACK|XXX)\b/.test(line)) {
+      push(findings, {
+        id: "loose-or-temporary-marker",
+        title: "Loose type or temporary marker",
+        category: "maintainability",
+        severity: line.includes("any") ? "medium" : "low",
+        file: file.relativePath,
+        lines: String(lineNo),
+        evidence: raw.trim(),
+        recommendation:
+          "Replace temporary markers with a tracked issue or tighten the type/implementation now.",
+      });
+    }
+
+    if (/\b(if|for|while|catch|case|&&|\|\|)\b/.test(line)) currentFunctionComplexity += 1;
+    if (/\b(function|async function)\b|=>\s*\{/.test(line) && functionStart === null) {
+      functionStart = lineNo;
+      currentFunctionComplexity = 1;
+      functionBraceDepth = 0;
+    }
+    if (functionStart !== null) {
+      functionBraceDepth += (raw.match(/\{/g) ?? []).length;
+      functionBraceDepth -= (raw.match(/\}/g) ?? []).length;
+      if (functionBraceDepth <= 0 && lineNo > functionStart) {
+        if (lineNo - functionStart > 80 || currentFunctionComplexity > 12) {
+          push(findings, {
+            id: "large-complex-function",
+            title: "Large or complex function",
+            category: "complexity",
+            severity:
+              currentFunctionComplexity > 18 || lineNo - functionStart > 140 ? "high" : "medium",
+            file: file.relativePath,
+            lines: lineRange(functionStart, lineNo),
+            evidence: `${lineNo - functionStart + 1} lines, approximate branch count ${currentFunctionComplexity}`,
+            recommendation:
+              "Split orchestration from decisions; extract named helpers only around stable concepts, not arbitrary line chunks.",
+          });
+        }
+        functionStart = null;
+      }
+    }
+  });
+
+  for (const [line, occurrences] of counts) {
+    if (occurrences.length < 3) continue;
+    push(findings, {
+      id: "repeated-line",
+      title: "Repeated implementation line",
+      category: "duplication",
+      severity: occurrences.length >= 6 ? "medium" : "low",
+      file: file.relativePath,
+      lines: occurrences.slice(0, 6).join(","),
+      evidence: line,
+      recommendation:
+        "Check whether these repeated lines represent copy-paste logic that should share a helper or table-driven representation.",
+    });
+  }
+
+  return findings;
+}
+
+export async function runProgrammaticChecks(options: ScanOptions): Promise<ProgrammaticCheck[]> {
+  const maxFiles = options.maxFiles ?? 300;
+  const targets = options.paths.length > 0 ? options.paths : ["."];
+  const files: string[] = [];
+  for (const target of targets) await collectFiles(options.cwd, target, files, maxFiles);
+
+  const findings: ProgrammaticCheck[] = [];
+  for (const absolutePath of files) {
+    const text = await readFile(absolutePath, "utf8").catch(() => "");
+    if (!text) continue;
+    findings.push(
+      ...scanFile({
+        absolutePath,
+        relativePath: path.relative(options.cwd, absolutePath),
+        text,
+        lines: text.split(/\r?\n/),
+      }),
+    );
+  }
+
+  return findings;
+}

package/src/code-smell/prompt.ts

@@ -0,0 +1,59 @@
+export const CODE_SMELL_PROMPT = `# Code Smell: Find and Clean Structural Problems
+
+You are a code smell reviewer. Find code that is likely to become costly to maintain, then propose small, behavior-preserving cleanups.
+
+Match the user's language for all candidate fields; if the user's request is in Chinese, write \`smell\`, \`evidence\`, \`impact\`, and \`recommendation\` in Chinese.
+
+## Two Analysis Tracks
+
+### 1. Programmatic Checks
+
+First call \`code_smell_scan\` for the requested paths (or the repository root if no paths are specified). Treat these results as leads, not truth. Verify each important finding by reading the relevant file before returning it.
+
+### 2. Agent/Skill Review
+
+Then inspect code using these smell families:
+
+- **Complexity**: long functions, mixed responsibilities, deep nesting, boolean flag control flow, branch-heavy conditionals
+- **Duplication**: copy-paste blocks, repeated condition chains, parallel representations of the same concept
+- **Coupling**: modules reaching through boundaries, feature code importing internals, circular-feeling dependencies
+- **State**: redundant derived state, mutable globals, caches without invalidation, multiple sources of truth
+- **Errors**: swallowed errors, empty catch blocks, broad catch that hides failures, inconsistent error mapping
+- **Performance**: N+1 loops, repeated I/O, sequential awaits for independent work, hot-path blocking work
+- **Maintainability**: debug remnants, commented-out code, TODO/HACK that hides required design, stringly-typed constants
+
+## Return Only Actionable Smells
+
+Every returned smell must include a real cause-effect chain:
+
+1. \`smell\` — the root structural problem in the current code.
+2. \`evidence\` — the concrete code evidence: symbol, repeated pattern, line, or tool finding.
+3. \`impact\` — what gets worse if left unchanged: divergent behavior, missed errors, repeated edits, N+1 calls, test brittleness.
+4. \`recommendation\` — a small, behavior-preserving next step.
+
+Do not flag subjective style issues. Do not recommend large rewrites unless a small first slice is clear.
+
+## Severity and Confidence
+
+- \`severity\`: \`high\` if likely bug/perf/user impact, \`medium\` if maintenance cost is concrete, \`low\` if cleanup is useful but not urgent.
+- \`confidence\`: \`high\` only after reading enough code to verify the smell; \`medium\` for strong tool-led hints; \`low\` only when the item is worth human inspection.
+
+## Output Format (REQUIRED)
+
+When analysis is complete, call the \`code_smell_findings\` tool exactly once as your final action. Put ALL findings in that tool call.
+
+Fields:
+- \`category\`: one of \`complexity\`, \`duplication\`, \`coupling\`, \`state\`, \`errors\`, \`performance\`, \`maintainability\`
+- \`severity\`: one of \`low\`, \`medium\`, \`high\`
+- \`confidence\`: one of \`low\`, \`medium\`, \`high\`
+- \`file\`: repository-relative path
+- \`lines\`: line number/range or empty string
+- \`smell\`: root problem
+- \`evidence\`: concrete proof
+- \`impact\`: real consequence if unchanged
+- \`recommendation\`: small fix
+- \`action\`: one of \`inspect\`, \`delete\`, \`inline\`, \`extract\`, \`refactor\`, \`guard\`
+
+If there are no findings, call \`code_smell_findings\` with an empty \`findings\` array.
+Do NOT write a prose-only final answer; the extension relies on the tool result.
+`;

package/src/code-smell/selector.ts

@@ -0,0 +1,157 @@
+import {
+  getSelectListTheme,
+  keyHint,
+  rawKeyHint,
+  type ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { matchesKey, SelectList, wrapTextWithAnsi, type SelectItem } from "@earendil-works/pi-tui";
+
+import type { CodeSmellFinding, SmellAction } from "./types.js";
+
+const SEVERITY_CONFIG = {
+  high: { label: "High severity" },
+  medium: { label: "Medium severity" },
+  low: { label: "Low severity" },
+} as const;
+
+const ACTION_LABEL: Record<SmellAction, string> = {
+  inspect: "Inspect manually",
+  delete: "Delete code",
+  inline: "Inline code",
+  extract: "Extract helper",
+  refactor: "Refactor",
+  guard: "Add guard/check",
+};
+
+export async function showFindingSelector(
+  ctx: ExtensionCommandContext,
+  findings: CodeSmellFinding[],
+): Promise<CodeSmellFinding[]> {
+  if (findings.length === 0) return [];
+
+  const sorted = [...findings].sort((a, b) => {
+    const rank = { high: 0, medium: 1, low: 2 } as const;
+    return rank[a.severity] - rank[b.severity];
+  });
+
+  const listItems: SelectItem[] = sorted.map((finding, index) => ({
+    value: String(index),
+    label: "",
+    description: `${SEVERITY_CONFIG[finding.severity].label} · ${finding.confidence} confidence · ${ACTION_LABEL[finding.action]}`,
+  }));
+
+  const selectedSet = new Set<number>();
+  sorted.forEach((finding, index) => {
+    if (finding.severity === "high" && finding.confidence !== "low") selectedSet.add(index);
+  });
+
+  const maxVisible = 8;
+  let cursorPos = 0;
+  const getStartIndex = (selectedIndex: number) =>
+    Math.max(0, Math.min(selectedIndex - Math.floor(maxVisible / 2), sorted.length - maxVisible));
+
+  const result = await ctx.ui.custom<CodeSmellFinding[]>((tui, theme, keybindings, done) => {
+    const updateListLabel = (index: number) => {
+      const item = listItems[index];
+      const finding = sorted[index];
+      const checkbox = selectedSet.has(index) ? "[x]" : "[ ]";
+      const location = finding.lines ? `${finding.file}:${finding.lines}` : finding.file;
+      item.label = `${checkbox} ${location}`;
+    };
+    const updateAll = () => listItems.forEach((_item, index) => updateListLabel(index));
+    updateAll();
+
+    const selectList = new SelectList(listItems, maxVisible, getSelectListTheme());
+    selectList.onSelectionChange = (item) => {
+      cursorPos = Number(item.value);
+    };
+    selectList.onCancel = () => done([]);
+
+    const toggleCurrent = () => {
+      if (selectedSet.has(cursorPos)) selectedSet.delete(cursorPos);
+      else selectedSet.add(cursorPos);
+      updateListLabel(cursorPos);
+      tui.requestRender();
+    };
+
+    const toggleAll = () => {
+      if (selectedSet.size === sorted.length) selectedSet.clear();
+      else for (let i = 0; i < sorted.length; i++) selectedSet.add(i);
+      updateAll();
+      tui.requestRender();
+    };
+
+    return {
+      render(width: number) {
+        selectList.setSelectedIndex(cursorPos);
+        const lines: string[] = [];
+        lines.push(theme.bold("Code Smell: Select findings to clean"));
+        lines.push(theme.fg("muted", `Found ${findings.length} findings`));
+        lines.push("");
+
+        const listLines = selectList.render(width);
+        const selectedLineIndex = cursorPos - getStartIndex(cursorPos);
+        const current = sorted[cursorPos];
+        for (const [lineIndex, line] of listLines.entries()) {
+          lines.push(line);
+          if (lineIndex !== selectedLineIndex || !current) continue;
+
+          const detailIndent = "    ";
+          const detailPrefix = `${detailIndent}│ `;
+          const wrapWidth = Math.max(1, width - detailPrefix.length);
+          const pushSection = (heading: string, body: string) => {
+            if (!body) return;
+            lines.push(theme.fg("borderMuted", `${detailIndent}┌─ ${heading}`));
+            lines.push(
+              ...wrapTextWithAnsi(body, wrapWidth).map((wrappedLine) =>
+                theme.fg("muted", `${detailPrefix}${wrappedLine}`),
+              ),
+            );
+          };
+
+          pushSection("Smell", current.smell);
+          pushSection("Evidence", current.evidence);
+          pushSection("Impact", current.impact);
+          pushSection("Recommendation", current.recommendation);
+          lines.push(theme.fg("muted", `${detailPrefix}Category: ${current.category}`));
+          lines.push(theme.fg("muted", `${detailPrefix}Action: ${ACTION_LABEL[current.action]}`));
+          lines.push(
+            theme.fg("borderMuted", `${detailIndent}└─ ${rawKeyHint("space", "selects this fix")}`),
+          );
+        }
+
+        lines.push("");
+        lines.push(
+          theme.fg(
+            "muted",
+            [
+              `Selected: ${selectedSet.size}`,
+              rawKeyHint("↑↓", "navigate"),
+              rawKeyHint("space", "toggle"),
+              rawKeyHint("a", "select all"),
+              keyHint("tui.select.confirm", "confirm"),
+              keyHint("tui.select.cancel", "cancel"),
+            ].join(" • "),
+          ),
+        );
+        return lines;
+      },
+      invalidate() {
+        selectList.invalidate();
+      },
+      handleInput(data: string) {
+        if (keybindings.matches(data, "tui.select.confirm")) {
+          return done(Array.from(selectedSet).map((i) => sorted[i]));
+        }
+        if (keybindings.matches(data, "tui.select.cancel")) return done([]);
+        if (matchesKey(data, "space")) return toggleCurrent();
+        if (matchesKey(data, "a")) return toggleAll();
+        const previous = cursorPos;
+        selectList.handleInput(data);
+        if (cursorPos !== previous) tui.requestRender();
+      },
+    };
+  });
+
+  return result ?? [];
+}

package/src/code-smell/types.ts

@@ -0,0 +1,36 @@
+export type SmellCategory =
+  | "complexity"
+  | "duplication"
+  | "coupling"
+  | "state"
+  | "errors"
+  | "performance"
+  | "maintainability";
+
+export type SmellSeverity = "low" | "medium" | "high";
+export type SmellConfidence = "low" | "medium" | "high";
+export type SmellAction = "inspect" | "delete" | "inline" | "extract" | "refactor" | "guard";
+
+export type CodeSmellFinding = {
+  category: SmellCategory;
+  severity: SmellSeverity;
+  confidence: SmellConfidence;
+  file: string;
+  lines: string;
+  smell: string;
+  evidence: string;
+  impact: string;
+  recommendation: string;
+  action: SmellAction;
+};
+
+export type ProgrammaticCheck = {
+  id: string;
+  title: string;
+  category: SmellCategory;
+  severity: SmellSeverity;
+  file: string;
+  lines: string;
+  evidence: string;
+  recommendation: string;
+};

package/src/code-smell/workflow.ts

@@ -0,0 +1,334 @@
+import {
+  defineTool,
+  DynamicBorder,
+  getSelectListTheme,
+  keyHint,
+  type ExtensionAPI,
+  type ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { Container, SelectList, Text, type SelectItem } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+import { runProgrammaticChecks } from "./checks.js";
+import { CODE_SMELL_PROMPT } from "./prompt.js";
+import { showFindingSelector } from "./selector.js";
+import type { CodeSmellFinding } from "./types.js";
+
+const categorySchema = Type.Union([
+  Type.Literal("complexity"),
+  Type.Literal("duplication"),
+  Type.Literal("coupling"),
+  Type.Literal("state"),
+  Type.Literal("errors"),
+  Type.Literal("performance"),
+  Type.Literal("maintainability"),
+]);
+const severitySchema = Type.Union([
+  Type.Literal("low"),
+  Type.Literal("medium"),
+  Type.Literal("high"),
+]);
+const confidenceSchema = Type.Union([
+  Type.Literal("low"),
+  Type.Literal("medium"),
+  Type.Literal("high"),
+]);
+const actionSchema = Type.Union([
+  Type.Literal("inspect"),
+  Type.Literal("delete"),
+  Type.Literal("inline"),
+  Type.Literal("extract"),
+  Type.Literal("refactor"),
+  Type.Literal("guard"),
+]);
+
+type Target = { paths: string[] };
+
+function parsePaths(value: string): string[] {
+  return value
+    .split(/\s+/)
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+}
+
+async function showPathInput(ctx: ExtensionCommandContext): Promise<Target | null> {
+  const result = await ctx.ui.editor(
+    "Enter folders/files to scan (space-separated or one per line):",
+    ".",
+  );
+  const paths = parsePaths(result ?? "");
+  return paths.length > 0 ? { paths } : null;
+}
+
+async function showTargetSelector(ctx: ExtensionCommandContext): Promise<Target | null> {
+  const items: SelectItem[] = [
+    { value: "repo", label: "Scan repository", description: "Programmatic checks + agent review" },
+    { value: "paths", label: "Scan selected paths", description: "Folders/files only" },
+  ];
+
+  const result = await ctx.ui.custom<"repo" | "paths" | null>((tui, theme, _kb, done) => {
+    const container = new Container();
+    container.addChild(new DynamicBorder((str) => theme.fg("accent", str)));
+    container.addChild(new Text(theme.fg("accent", theme.bold("Select code smell scope"))));
+    const selectList = new SelectList(items, 6, getSelectListTheme());
+    selectList.onSelect = (item) => done(item.value as "repo" | "paths");
+    selectList.onCancel = () => done(null);
+    container.addChild(selectList);
+    container.addChild(
+      new Text(
+        `${keyHint("tui.select.confirm", "confirm")}  ${keyHint("tui.select.cancel", "cancel")}`,
+      ),
+    );
+    container.addChild(new DynamicBorder((str) => theme.fg("accent", str)));
+    return {
+      render(width: number) {
+        return container.render(width);
+      },
+      invalidate() {
+        container.invalidate();
+      },
+      handleInput(data: string) {
+        selectList.handleInput(data);
+        tui.requestRender();
+      },
+    };
+  });
+
+  if (!result) return null;
+  if (result === "repo") return { paths: ["."] };
+  return showPathInput(ctx);
+}
+
+function registerScanTool(pi: ExtensionAPI) {
+  pi.registerTool(
+    defineTool({
+      name: "code_smell_scan",
+      label: "Code Smell Scan",
+      description: "Run programmatic code smell checks over repository paths.",
+      promptSnippet:
+        "Run deterministic checks for debug remnants, commented-out code, duplication, and complex functions",
+      promptGuidelines: [
+        "Use code_smell_scan before manual code smell review, then verify important findings by reading files.",
+      ],
+      parameters: Type.Object({
+        paths: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+        maxFiles: Type.Optional(Type.Number({ minimum: 1, maximum: 1000 })),
+      }),
+      async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        const findings = await runProgrammaticChecks({
+          cwd: ctx.cwd,
+          paths: params.paths ?? ["."],
+          maxFiles: params.maxFiles,
+        });
+        const bySeverity = {
+          high: findings.filter((f) => f.severity === "high").length,
+          medium: findings.filter((f) => f.severity === "medium").length,
+          low: findings.filter((f) => f.severity === "low").length,
+        };
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Found ${findings.length} programmatic code-smell leads.`,
+            },
+          ],
+          details: { findings, bySeverity },
+        };
+      },
+    }),
+  );
+}
+
+function registerFindingsTool(
+  pi: ExtensionAPI,
+  state: {
+    getResolver: () => ((findings: CodeSmellFinding[]) => void) | null;
+    clearResolver: () => void;
+    setLatestFindings: (findings: CodeSmellFinding[]) => void;
+  },
+) {
+  pi.registerTool(
+    defineTool({
+      name: "code_smell_findings",
+      label: "Code Smell Findings",
+      description:
+        "Return the complete finding list for /code-smell. Use as the final action after analysis.",
+      promptSnippet:
+        "Return structured code smell findings for /code-smell as a terminating result",
+      promptGuidelines: [
+        "Use code_smell_findings exactly once as the final action when the /code-smell command asks for findings.",
+      ],
+      parameters: Type.Object({
+        findings: Type.Array(
+          Type.Object({
+            category: categorySchema,
+            severity: severitySchema,
+            confidence: confidenceSchema,
+            file: Type.String({ minLength: 1, pattern: "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$" }),
+            lines: Type.String(),
+            smell: Type.String({ minLength: 1 }),
+            evidence: Type.String({ minLength: 1 }),
+            impact: Type.String({ minLength: 1 }),
+            recommendation: Type.String({ minLength: 1 }),
+            action: actionSchema,
+          }),
+        ),
+      }),
+      async execute(_toolCallId, params) {
+        const findings: CodeSmellFinding[] = params.findings;
+        const resolve = state.getResolver();
+        if (!resolve) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: "Ignored code smell findings because no /code-smell analysis is pending.",
+              },
+            ],
+            details: { ignored: true, findings: [] },
+            terminate: true,
+          };
+        }
+        state.setLatestFindings(findings);
+        state.clearResolver();
+        resolve(findings);
+        return {
+          content: [
+            { type: "text" as const, text: `Captured ${findings.length} code smell findings.` },
+          ],
+          details: { ignored: false, findings },
+          terminate: true,
+        };
+      },
+    }),
+  );
+}
+
+function buildPrompt(target: Target, focus?: string): string {
+  let prompt = CODE_SMELL_PROMPT;
+  const isRepoRoot = target.paths.length === 1 && target.paths[0] === ".";
+  if (!isRepoRoot)
+    prompt += `\n\n## Scope\n\nReview only these repository-relative paths: ${target.paths.join(", ")}.`;
+  if (focus?.trim()) prompt += `\n\n## Additional Focus\n\n${focus.trim()}`;
+  return prompt;
+}
+
+async function applyFindings(
+  ctx: ExtensionCommandContext,
+  selected: CodeSmellFinding[],
+  pi: ExtensionAPI,
+) {
+  if (selected.length === 0) {
+    ctx.ui.notify("No code smell findings selected", "info");
+    return;
+  }
+
+  const prompt = `# Clean Selected Code Smells\n\nApply small, behavior-preserving fixes for these selected findings:\n\n${selected
+    .map(
+      (f) =>
+        `- ${f.file} (${f.lines || "?"}) [${f.action}] ${f.category}/${f.severity}\n  - Smell: ${f.smell}\n  - Evidence: ${f.evidence}\n  - Recommendation: ${f.recommendation}`,
+    )
+    .join(
+      "\n",
+    )}\n\nRules:\n1. Read each file before editing.\n2. Keep changes minimal and behavior-preserving.\n3. Skip any item whose fix is ambiguous and report why.\n4. Run relevant tests/type-check/lint after changes.\n5. Report changed files and verification output.`;
+
+  ctx.ui.notify(`Applying ${selected.length} selected code smell fixes`, "info");
+  pi.sendUserMessage(prompt);
+}
+
+export function registerCodeSmellWorkflow(pi: ExtensionAPI) {
+  let resolvePendingTurnStart: (() => void) | null = null;
+  let resolvePendingFindingsTool: ((findings: CodeSmellFinding[]) => void) | null = null;
+  let latestToolFindings: CodeSmellFinding[] | null = null;
+
+  pi.on("turn_start", () => {
+    if (!resolvePendingTurnStart) return;
+    const resolve = resolvePendingTurnStart;
+    resolvePendingTurnStart = null;
+    resolve();
+  });
+
+  registerScanTool(pi);
+  registerFindingsTool(pi, {
+    getResolver: () => resolvePendingFindingsTool,
+    clearResolver: () => {
+      resolvePendingFindingsTool = null;
+    },
+    setLatestFindings: (findings) => {
+      latestToolFindings = findings;
+    },
+  });
+
+  pi.registerCommand("code-smell", {
+    description:
+      "Find code smells with programmatic checks and agent review, then optionally clean them",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("Code smell workflow requires interactive mode", "error");
+        return;
+      }
+      if (!ctx.isIdle()) {
+        ctx.ui.notify("Cannot run code-smell while agent is busy", "warning");
+        return;
+      }
+
+      const paths = parsePaths(args);
+      let target: Target | null = paths.length > 0 ? { paths } : null;
+      if (!target) target = await showTargetSelector(ctx);
+      if (!target) {
+        ctx.ui.notify("Code smell scan cancelled", "info");
+        return;
+      }
+
+      latestToolFindings = null;
+      const turnStarted = new Promise<void>((r) => {
+        resolvePendingTurnStart = r;
+      });
+      const toolResult = new Promise<CodeSmellFinding[]>((r) => {
+        resolvePendingFindingsTool = r;
+      });
+
+      ctx.ui.notify(`Analyzing code smells in ${target.paths.join(", ")}`, "info");
+      pi.sendUserMessage(buildPrompt(target));
+
+      const started = await Promise.race<boolean>([
+        turnStarted.then(() => true),
+        new Promise<boolean>((r) => setTimeout(() => r(false), 10000)),
+      ]);
+      if (!started) {
+        resolvePendingTurnStart = null;
+        resolvePendingFindingsTool = null;
+        ctx.ui.notify("Analysis did not start within 10 seconds", "warning");
+        return;
+      }
+
+      await ctx.waitForIdle();
+      const findings =
+        latestToolFindings ??
+        (await Promise.race<CodeSmellFinding[] | null>([
+          toolResult,
+          new Promise<null>((r) => setTimeout(() => r(null), 100)),
+        ]));
+      resolvePendingFindingsTool = null;
+
+      if (findings === null) {
+        ctx.ui.notify(
+          "Could not read findings — model did not call code_smell_findings",
+          "warning",
+        );
+        return;
+      }
+      if (findings.length === 0) {
+        ctx.ui.notify("No code smells found", "info");
+        return;
+      }
+
+      const selected = await showFindingSelector(ctx, findings);
+      if (!selected || selected.length === 0) {
+        ctx.ui.notify("Code smell cleanup cancelled", "info");
+        return;
+      }
+      await applyFindings(ctx, selected, pi);
+    },
+  });
+}

package/{prompt.ts → src/simplify/prompt.ts}

@@ -25,8 +25,15 @@ Before flagging, **search the codebase** (utility directories, shared modules, f
 #### B3. Commented-out Code (Review)
 - Old logic left in comments, disabled features, uncustomized templates
 
-#### B4. Over-engineering (Confirm)
+#### B4. Over-engineering / Thin Wrappers (Confirm)
 - Abstractions created "for future use" but unused, single-call-site helpers that should be inlined, useless indirection
+- Thin wrappers that only rename another function or constructor without adding validation, policy, error handling, logging, or a stable public boundary
+- Platform-specific wrapper modules that merely re-export generic session/config helpers under different names
+- Method wrappers on classes that only delegate to a free function already available to callers
+- Test-only exported helpers that can use the real internal/public helper directly instead
+- Small formatting/command helpers whose name repeats a one-line call and have only one call site
+
+**Thin-wrapper discipline:** prefer deleting the wrapper and calling the underlying primitive directly when the wrapper has no independent semantic responsibility. Keep the wrapper if it protects a public API, documents a domain boundary, centralizes cross-cutting behavior, or isolates an unstable dependency.
 
 #### B5. Hacky Patterns (Confirm)
 - **Redundant state**: state that duplicates other state, cached values that could be derived, observers that could be direct calls
@@ -57,6 +64,20 @@ Before flagging, **search the codebase** (utility directories, shared modules, f
    - Assign **category** (reuse / quality / efficiency) and **risk**
    - State the concrete fix (which existing utility to call, which lines to delete, how to parallelize, etc.)
 
+## Thin Wrapper Review Heuristics
+
+When hunting simplification opportunities, explicitly scan for these patterns:
+
+- **Rename-only wrapper:** \`foo()\` only calls \`bar()\` with the same inputs. Inline \`bar()\` unless \`foo\` is a real public/domain concept.
+- **Constructor/factory wrapper:** \`createX(args)\` only returns \`new X(args)\`. Inline construction unless the factory selects implementations or enforces policy.
+- **Scope-specific alias:** \`SlackThing\`/\`ConversationThing\` only wraps a generic helper. Delete it if the generic name is already clear at call sites.
+- **Single-call-site helper:** a helper with one caller and no meaningful name compression. Inline it, especially for one-line formatting, parsing, or path helpers.
+- **Duplicated write APIs:** several \`saveFooConfig\` functions patch different fields in the same file. Consolidate into one \`updateSettings(patch)\`-style API.
+- **Test-only export:** exported solely so tests can call a thin wrapper. Test the underlying public helper or observable behavior instead.
+- **Pass-through class method:** a class method only delegates to a module-level function and is not required by an interface. Remove the method or call the function directly.
+
+Do **not** flag wrappers whose consequence is only "one extra line". Flag them when they create a real maintenance cost: multiple ways to do the same operation, unclear source of truth, misleading domain boundaries, duplicated tests for delegated behavior, or user/developer uncertainty about which API is authoritative.
+
 ## Risk Levels
 
 - **safe**: Definitely apply (dead code, debug remnants)

package/tsconfig.json

@@ -6,6 +6,7 @@
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
-    "outDir": "dist"
+    "outDir": "dist",
+    "rootDir": "."
   }
 }