supipowers 1.2.6 → 1.5.0

package/src/review/agent-loader.ts

@@ -0,0 +1,331 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import correctnessAgentTemplate from "./default-agents/correctness.md" with { type: "text" };
+import maintainabilityAgentTemplate from "./default-agents/maintainability.md" with { type: "text" };
+import securityAgentTemplate from "./default-agents/security.md" with { type: "text" };
+import type { PlatformPaths } from "../platform/types.js";
+import type {
+  ConfiguredReviewAgent,
+  ReviewAgentConfig,
+  ReviewAgentDefinition,
+  ReviewAgentsConfig,
+} from "../types.js";
+import { normalizeLineEndings } from "../text.js";
+import {
+  ReviewAgentFrontmatterSchema,
+  ReviewAgentsConfigSchema,
+  collectReviewValidationErrors,
+  formatReviewValidationErrors,
+} from "./types.js";
+
+const REVIEW_AGENTS_DIR = "review-agents";
+const CONFIG_FILE = "config.yml";
+
+const DEFAULT_AGENT_TEMPLATES: Record<string, string> = {
+  "security.md": securityAgentTemplate,
+  "correctness.md": correctnessAgentTemplate,
+  "maintainability.md": maintainabilityAgentTemplate,
+};
+
+const DEFAULT_REVIEW_AGENTS_CONFIG: ReviewAgentConfig[] = [
+  { name: "security", enabled: true, data: "security.md", model: null },
+  { name: "correctness", enabled: true, data: "correctness.md", model: null },
+  { name: "maintainability", enabled: true, data: "maintainability.md", model: null },
+];
+
+export interface LoadedReviewAgents {
+  agentsDir: string;
+  configPath: string;
+  config: ReviewAgentsConfig;
+  agents: ConfiguredReviewAgent[];
+}
+
+function buildDefaultConfigText(): string {
+  return [
+    "agents:",
+    ...DEFAULT_REVIEW_AGENTS_CONFIG.flatMap((agent) => [
+      `  - name: ${agent.name}`,
+      `    enabled: ${agent.enabled}`,
+      `    data: ${agent.data}`,
+      "    model: null",
+    ]),
+    "",
+  ].join("\n");
+}
+
+function writeIfMissing(filePath: string, content: string): void {
+  if (fs.existsSync(filePath)) {
+    return;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+}
+
+function validateReviewAgentsConfig(data: unknown): ReviewAgentsConfig {
+  const errors = formatReviewValidationErrors(collectReviewValidationErrors(ReviewAgentsConfigSchema, data));
+  if (errors.length > 0) {
+    throw new Error(`Invalid review-agents config: ${errors.join("; ")}`);
+  }
+  return data as ReviewAgentsConfig;
+}
+
+async function importYamlFile(filePath: string): Promise<unknown> {
+  const stat = fs.statSync(filePath);
+  const url = pathToFileURL(filePath);
+  const imported = await import(`${url.href}?mtime=${stat.mtimeMs}`, { with: { type: "yaml" } });
+  return imported.default;
+}
+
+function parseFrontmatter(frontmatter: string, filePath: string): ReviewAgentDefinition {
+  const metadata: Record<string, unknown> = {};
+
+  for (const line of frontmatter.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+
+    const separator = trimmed.indexOf(":");
+    if (separator === -1) {
+      continue;
+    }
+
+    const key = trimmed.slice(0, separator).trim();
+    const value = trimmed.slice(separator + 1).trim();
+    metadata[key] = value;
+  }
+
+  const errors = formatReviewValidationErrors(
+    collectReviewValidationErrors(ReviewAgentFrontmatterSchema, metadata),
+  );
+  if (errors.length > 0) {
+    throw new Error(`Invalid agent frontmatter in ${filePath}: ${errors.join("; ")}`);
+  }
+
+  return {
+    name: String(metadata.name),
+    description: String(metadata.description),
+    focus: typeof metadata.focus === "string" ? metadata.focus : null,
+    prompt: "",
+    filePath,
+  };
+}
+
+export function parseReviewAgentMarkdown(content: string, filePath: string): ReviewAgentDefinition {
+  const normalized = normalizeLineEndings(content);
+  const match = normalized.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) {
+    throw new Error(`Review agent file ${filePath} is missing YAML frontmatter.`);
+  }
+
+  const definition = parseFrontmatter(match[1], filePath);
+  const prompt = match[2]?.trim();
+  if (!prompt) {
+    throw new Error(`Review agent file ${filePath} has an empty prompt body.`);
+  }
+
+  return {
+    ...definition,
+    prompt,
+  };
+}
+
+export function getReviewAgentsDir(paths: PlatformPaths, cwd: string): string {
+  return paths.project(cwd, REVIEW_AGENTS_DIR);
+}
+
+export function getReviewAgentsConfigPath(paths: PlatformPaths, cwd: string): string {
+  return path.join(getReviewAgentsDir(paths, cwd), CONFIG_FILE);
+}
+
+export function ensureDefaultReviewAgents(paths: PlatformPaths, cwd: string): void {
+  const agentsDir = getReviewAgentsDir(paths, cwd);
+  fs.mkdirSync(agentsDir, { recursive: true });
+
+  for (const [fileName, content] of Object.entries(DEFAULT_AGENT_TEMPLATES)) {
+    writeIfMissing(path.join(agentsDir, fileName), content);
+  }
+
+  writeIfMissing(getReviewAgentsConfigPath(paths, cwd), buildDefaultConfigText());
+}
+
+export async function loadReviewAgentsConfig(paths: PlatformPaths, cwd: string): Promise<ReviewAgentsConfig> {
+  ensureDefaultReviewAgents(paths, cwd);
+  return validateReviewAgentsConfig(await importYamlFile(getReviewAgentsConfigPath(paths, cwd)));
+}
+
+export async function loadReviewAgents(paths: PlatformPaths, cwd: string): Promise<LoadedReviewAgents> {
+  const agentsDir = getReviewAgentsDir(paths, cwd);
+  const configPath = getReviewAgentsConfigPath(paths, cwd);
+  const config = await loadReviewAgentsConfig(paths, cwd);
+
+  const agents = config.agents
+    .filter((agent) => agent.enabled)
+    .map((agent) => {
+      const filePath = path.join(agentsDir, agent.data);
+      if (!fs.existsSync(filePath)) {
+        throw new Error(`Configured review agent file does not exist: ${filePath}`);
+      }
+
+      const definition = parseReviewAgentMarkdown(fs.readFileSync(filePath, "utf-8"), filePath);
+      if (definition.name !== agent.name) {
+        throw new Error(
+          `Configured agent name \"${agent.name}\" does not match frontmatter name \"${definition.name}\" in ${filePath}.`,
+        );
+      }
+
+      return {
+        ...definition,
+        enabled: agent.enabled,
+        data: agent.data,
+        model: agent.model,
+      } satisfies ConfiguredReviewAgent;
+    });
+
+  return {
+    agentsDir,
+    configPath,
+    config,
+    agents,
+  };
+}
+
+// ── Global Agent Support ────────────────────────────────────
+
+export function getGlobalReviewAgentsDir(paths: PlatformPaths): string {
+  return paths.global(REVIEW_AGENTS_DIR);
+}
+
+export function getGlobalReviewAgentsConfigPath(paths: PlatformPaths): string {
+  return path.join(getGlobalReviewAgentsDir(paths), CONFIG_FILE);
+}
+
+export function ensureGlobalDefaultReviewAgents(paths: PlatformPaths): void {
+  const agentsDir = getGlobalReviewAgentsDir(paths);
+  fs.mkdirSync(agentsDir, { recursive: true });
+
+  for (const [fileName, content] of Object.entries(DEFAULT_AGENT_TEMPLATES)) {
+    writeIfMissing(path.join(agentsDir, fileName), content);
+  }
+
+  writeIfMissing(getGlobalReviewAgentsConfigPath(paths), buildDefaultConfigText());
+}
+
+export async function loadGlobalReviewAgentsConfig(paths: PlatformPaths): Promise<ReviewAgentsConfig> {
+  ensureGlobalDefaultReviewAgents(paths);
+  return validateReviewAgentsConfig(await importYamlFile(getGlobalReviewAgentsConfigPath(paths)));
+}
+
+export async function loadGlobalReviewAgents(paths: PlatformPaths): Promise<LoadedReviewAgents> {
+  const agentsDir = getGlobalReviewAgentsDir(paths);
+  const configPath = getGlobalReviewAgentsConfigPath(paths);
+  const config = await loadGlobalReviewAgentsConfig(paths);
+
+  const agents = config.agents
+    .filter((agent) => agent.enabled)
+    .map((agent) => {
+      const filePath = path.join(agentsDir, agent.data);
+      if (!fs.existsSync(filePath)) {
+        throw new Error(`Configured review agent file does not exist: ${filePath}`);
+      }
+
+      const definition = parseReviewAgentMarkdown(fs.readFileSync(filePath, "utf-8"), filePath);
+      if (definition.name !== agent.name) {
+        throw new Error(
+          `Configured agent name "${agent.name}" does not match frontmatter name "${definition.name}" in ${filePath}.`,
+        );
+      }
+
+      return {
+        ...definition,
+        enabled: agent.enabled,
+        data: agent.data,
+        model: agent.model,
+        scope: "global" as const,
+      } satisfies ConfiguredReviewAgent;
+    });
+
+  return {
+    agentsDir,
+    configPath,
+    config,
+    agents,
+  };
+}
+
+// ── Merged Loading (Global + Project) ──────────────────────
+
+export async function loadMergedReviewAgents(
+  paths: PlatformPaths,
+  cwd: string,
+): Promise<LoadedReviewAgents> {
+  const globalResult = await loadGlobalReviewAgents(paths);
+  const projectResult = await loadReviewAgents(paths, cwd);
+
+  // Tag project agents with scope
+  const projectAgents = projectResult.agents.map((agent) => ({
+    ...agent,
+    scope: "project" as const,
+  }));
+
+  // Project agents override global agents with the same name
+  const projectNames = new Set(projectAgents.map((a) => a.name));
+  const uniqueGlobalAgents = globalResult.agents.filter((a) => !projectNames.has(a.name));
+
+  return {
+    agentsDir: projectResult.agentsDir,
+    configPath: projectResult.configPath,
+    config: projectResult.config,
+    agents: [...uniqueGlobalAgents, ...projectAgents],
+  };
+}
+
+// ── Write Helpers ──────────────────────────────────────────
+
+export function writeAgentFile(
+  agentsDir: string,
+  name: string,
+  frontmatter: { name: string; description: string; focus: string | null },
+  promptBody: string,
+): string {
+  const fileName = `${name}.md`;
+  const filePath = path.join(agentsDir, fileName);
+  const focusLine = frontmatter.focus ? `\nfocus: ${frontmatter.focus}` : "";
+  const content = `---\nname: ${frontmatter.name}\ndescription: ${frontmatter.description}${focusLine}\n---\n\n${promptBody}\n`;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+  return fileName;
+}
+
+export async function addAgentToConfig(
+  configPath: string,
+  agent: ReviewAgentConfig,
+): Promise<void> {
+  let config: ReviewAgentsConfig;
+  try {
+    config = validateReviewAgentsConfig(await importYamlFile(configPath));
+  } catch {
+    config = { agents: [] };
+  }
+
+  // Idempotent: replace if name exists, append otherwise
+  const idx = config.agents.findIndex((a) => a.name === agent.name);
+  if (idx >= 0) {
+    config.agents[idx] = agent;
+  } else {
+    config.agents.push(agent);
+  }
+
+  const text = [
+    "agents:",
+    ...config.agents.flatMap((a) => [
+      `  - name: ${a.name}`,
+      `    enabled: ${a.enabled}`,
+      `    data: ${a.data}`,
+      `    model: ${a.model ?? "null"}`,
+    ]),
+    "",
+  ].join("\n");
+  fs.writeFileSync(configPath, text);
+}

package/src/review/consolidator.ts

@@ -0,0 +1,180 @@
+import type { ReviewFinding, ReviewOutput } from "../types.js";
+
+const PRIORITY_ORDER: Record<ReviewFinding["priority"], number> = {
+  P0: 0,
+  P1: 1,
+  P2: 2,
+  P3: 3,
+};
+
+const SEVERITY_ORDER: Record<ReviewFinding["severity"], number> = {
+  error: 0,
+  warning: 1,
+  info: 2,
+};
+
+function normalizeText(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .split(/\s+/)
+    .map((token) => token.trim())
+    .filter((token) => token.length >= 4);
+}
+
+function tokenSimilarity(left: string, right: string): number {
+  const leftTokens = normalizeText(left);
+  const rightTokens = normalizeText(right);
+  if (leftTokens.length === 0 || rightTokens.length === 0) {
+    return 0;
+  }
+
+  const leftSet = new Set(leftTokens);
+  const rightSet = new Set(rightTokens);
+  let shared = 0;
+  for (const token of leftSet) {
+    if (rightSet.has(token)) {
+      shared += 1;
+    }
+  }
+
+  return shared / Math.max(leftSet.size, rightSet.size);
+}
+
+function linesOverlap(left: ReviewFinding, right: ReviewFinding): boolean {
+  if (!left.file || !right.file || left.file !== right.file) {
+    return false;
+  }
+  if (left.lineStart === null || left.lineEnd === null || right.lineStart === null || right.lineEnd === null) {
+    return false;
+  }
+
+  return left.lineStart <= right.lineEnd && right.lineStart <= left.lineEnd;
+}
+
+function areDuplicateFindings(left: ReviewFinding, right: ReviewFinding): boolean {
+  if (!linesOverlap(left, right)) {
+    return false;
+  }
+
+  const titleSimilarity = tokenSimilarity(left.title, right.title);
+  const bodySimilarity = tokenSimilarity(left.body, right.body);
+  return titleSimilarity >= 0.4 || bodySimilarity >= 0.35;
+}
+
+function comparePriority(left: ReviewFinding, right: ReviewFinding): number {
+  const priorityDelta = PRIORITY_ORDER[left.priority] - PRIORITY_ORDER[right.priority];
+  if (priorityDelta !== 0) {
+    return priorityDelta;
+  }
+
+  const severityDelta = SEVERITY_ORDER[left.severity] - SEVERITY_ORDER[right.severity];
+  if (severityDelta !== 0) {
+    return severityDelta;
+  }
+
+  return right.confidence - left.confidence;
+}
+
+function mergeAgentLabels(left: string | undefined, right: string | undefined): string | undefined {
+  const labels = new Set(
+    [left, right]
+      .flatMap((value) => value?.split(",") ?? [])
+      .map((value) => value.trim())
+      .filter((value) => value.length > 0),
+  );
+
+  if (labels.size === 0) {
+    return undefined;
+  }
+
+  return [...labels].sort().join(",");
+}
+
+function mergeValidation(left: ReviewFinding, right: ReviewFinding): ReviewFinding["validation"] | undefined {
+  const candidates = [left.validation, right.validation].filter((value) => value !== undefined);
+  if (candidates.length === 0) {
+    return undefined;
+  }
+
+  const ranking = { confirmed: 0, uncertain: 1, rejected: 2 } as const;
+  candidates.sort((a, b) => ranking[a.verdict] - ranking[b.verdict]);
+  return candidates[0];
+}
+
+function mergeFindings(left: ReviewFinding, right: ReviewFinding): ReviewFinding {
+  const preferred = comparePriority(left, right) <= 0 ? left : right;
+  const alternate = preferred === left ? right : left;
+
+  return {
+    ...preferred,
+    confidence: Math.max(left.confidence, right.confidence),
+    suggestion: preferred.suggestion ?? alternate.suggestion,
+    agent: mergeAgentLabels(left.agent, right.agent),
+    validation: mergeValidation(left, right),
+  };
+}
+
+function sortFindings(findings: ReviewFinding[]): ReviewFinding[] {
+  return [...findings].sort((left, right) => {
+    const priority = comparePriority(left, right);
+    if (priority !== 0) {
+      return priority;
+    }
+
+    const fileLeft = left.file ?? "~";
+    const fileRight = right.file ?? "~";
+    const fileComparison = fileLeft.localeCompare(fileRight);
+    if (fileComparison !== 0) {
+      return fileComparison;
+    }
+
+    return (left.lineStart ?? Number.MAX_SAFE_INTEGER) - (right.lineStart ?? Number.MAX_SAFE_INTEGER);
+  });
+}
+
+function statusFromFindings(findings: ReviewFinding[]): ReviewOutput["status"] {
+  if (findings.length === 0) {
+    return "passed";
+  }
+
+  const hasValidation = findings.some((finding) => finding.validation !== undefined);
+  if (!hasValidation) {
+    return "failed";
+  }
+
+  if (findings.some((finding) => finding.validation?.verdict === "confirmed")) {
+    return "failed";
+  }
+  if (findings.some((finding) => finding.validation?.verdict === "uncertain")) {
+    return "blocked";
+  }
+  return "passed";
+}
+
+export function consolidateReviewFindings(findings: ReviewFinding[]): ReviewFinding[] {
+  const consolidated: ReviewFinding[] = [];
+
+  for (const finding of sortFindings(findings)) {
+    const index = consolidated.findIndex((candidate) => areDuplicateFindings(candidate, finding));
+    if (index === -1) {
+      consolidated.push(finding);
+      continue;
+    }
+
+    consolidated[index] = mergeFindings(consolidated[index], finding);
+  }
+
+  return sortFindings(consolidated);
+}
+
+export function consolidateReviewOutputs(outputs: ReviewOutput[]): ReviewOutput {
+  const allFindings = outputs.flatMap((output) => output.findings);
+  const findings = consolidateReviewFindings(allFindings);
+
+  return {
+    findings,
+    summary: `Consolidated ${allFindings.length} findings into ${findings.length} unique findings.`,
+    status: statusFromFindings(findings),
+  };
+}

package/src/review/default-agents/correctness.md

@@ -0,0 +1,72 @@
+---
+name: correctness
+description: Correctness-focused code reviewer targeting logic errors, edge cases, and contract violations
+focus: Logic and control flow, edge cases, error handling, state management, async correctness, type safety, contract fidelity
+---
+
+You are a correctness-focused code reviewer. Analyze the provided code diff for bugs, logic errors, and contract violations that would produce wrong results in production.
+
+## What to Check
+
+### Logic & Control Flow
+- Off-by-one errors — wrong loop bounds, fencepost errors, `<` vs `<=`
+- Wrong boolean operators — `&&` where `||` is needed, incorrect negation, missing parentheses around compound conditions
+- Operator precedence — implicit grouping that changes meaning (e.g., bitwise vs logical operators)
+- Unreachable code — dead branches after early returns, conditions that are always true/false
+- Short-circuit evaluation — relying on side effects in short-circuited expressions
+
+### Edge Cases & Boundary Conditions
+- Null/undefined inputs — missing guards on optional parameters or nullable return values
+- Empty collections — code that assumes at least one element (e.g., `array[0]` without length check)
+- Zero and negative values — division by zero, negative indices, unsigned/signed confusion
+- Overflow/underflow — integer arithmetic exceeding safe bounds, unbounded string/array growth
+- Single-element and max-boundary cases — code that works for N>1 but fails for N=0 or N=1
+
+### Error Handling & Failure Paths
+- Swallowed errors — empty `catch` blocks, `catch` that logs but doesn't rethrow or return a failure signal
+- Missing cleanup — resources (file handles, connections, timers) not released in `finally` or on early return
+- Fail-open patterns — exceptions that cause code to proceed as if nothing failed instead of aborting
+- Misleading error messages — error text that doesn't match the actual failure, or that omits the root cause
+- Unhandled promise rejections — async functions called without `await` or `.catch()`, floating promises
+
+### State Management
+- Invalid state transitions — state set to a value that violates the domain's invariants
+- Implicit state machines — multiple boolean flags used where a discriminated union or enum belongs
+- Stale state after async operations — reading state that may have changed during an `await`
+- Shared-state mutation — concurrent writers to the same object/array without coordination
+- Missing state resets — state that accumulates across invocations when it should be fresh each time
+
+### Async & Concurrency
+- Race conditions — time-of-check to time-of-use (TOCTTOU) gaps, read-modify-write without atomicity
+- Missing `await` — async function called but the returned promise is ignored
+- Parallel mutations — multiple concurrent operations modifying the same resource
+- Event listener leaks — listeners registered without corresponding cleanup or removal
+- Callback ordering assumptions — code that assumes callback A fires before callback B without a guarantee
+
+### Type & Data Integrity
+- Implicit coercions — `==` instead of `===`, truthy/falsy checks on values where `0`, `""`, or `false` are valid
+- Lossy conversions — float to integer truncation, string to number parsing without validation
+- Wrong data shape assumptions — accessing nested properties without verifying the structure exists
+- Unsafe casts — type assertions (`as`, `!`) that bypass the type checker without runtime validation
+- Missing type narrowing — using a union type without discriminating, leading to property access on the wrong variant
+
+### Contract Violations
+- Return values that don't match documented or implied behavior — function says it returns X but returns Y under certain paths
+- Partial results returned as complete — a function returns a subset of expected data without signaling incompleteness
+- Plausible output on failure — a function that fails but returns default-looking data instead of throwing or returning an error signal
+- Mismatched nullability — function declares a non-null return but has a code path that returns null/undefined
+
+## Severity Guide
+
+- **error**: Will produce wrong results, data corruption, or crash in production (e.g., off-by-one causing data loss, swallowed error hiding a failure, missing await dropping a write)
+- **warning**: Likely incorrect under certain inputs or conditions that may realistically arise (e.g., empty-array access without guard, stale state read after await)
+- **info**: Code smell that increases risk of future correctness bugs (e.g., implicit coercion, unsafe cast on stable code)
+
+## Out of Scope
+
+- Security vulnerabilities (handled by security agent)
+- Code style or formatting (handled by linter)
+- Maintainability concerns (handled by maintainability agent)
+- Performance optimizations
+
+{output_instructions}

package/src/review/default-agents/maintainability.md

@@ -0,0 +1,64 @@
+---
+name: maintainability
+description: Maintainability-focused code reviewer targeting readability, cohesion, coupling, and long-term cost
+focus: Readability, cohesion, coupling, duplication, abstraction quality, interface design, long-term cost
+---
+
+You are a maintainability-focused code reviewer. Analyze the provided code diff for patterns that increase the cost of future changes, obscure intent, or make the codebase harder to work with safely.
+
+## What to Check
+
+### Readability & Clarity
+- Misleading names — variables, functions, or types whose names suggest something different from what they actually do
+- Unclear intent — code that requires reading the implementation to understand the purpose, where a name or comment would suffice
+- Magic numbers and strings — unexplained literal values embedded in logic instead of named constants
+- Missing comments on non-obvious invariants — implicit assumptions, tradeoffs, or constraints that the next editor will not know
+- Inconsistent conventions — naming, patterns, or structure that departs from what the surrounding code does without justification
+
+### Cohesion & Responsibility
+- God classes or functions — units that do too many things, violating single-responsibility
+- Mixed levels of abstraction — high-level orchestration mixed with low-level manipulation in the same function
+- Feature envy — a function or method that is more interested in another module's data than its own, suggesting the logic belongs elsewhere
+
+### Coupling & Dependencies
+- Tight coupling to implementation details — callers depending on internal structure rather than a stable interface
+- Hidden dependencies — behavior that depends on global state, environment variables, or import side effects without making it explicit
+- Shotgun surgery — a single logical change that requires edits across many unrelated files, indicating a missing abstraction
+- Missing dependency inversion — concrete implementations hardcoded where an interface or injection point would reduce coupling
+
+### Duplication & Redundancy
+- Copy-pasted logic — identical or near-identical code blocks that should be extracted into a shared function
+- Near-duplicate functions — functions with minor variations that could be unified with a parameter or strategy
+- Knowledge in more than one place — the same business rule, constant, or mapping expressed redundantly across files
+
+### Abstraction Quality
+- Leaky abstractions — modules that expose internal details callers should not depend on
+- Incomplete abstractions — abstractions that handle most cases but force callers to work around them for the rest, giving the appearance of encapsulation without the reality
+- Premature abstractions — generalized solutions for problems that only exist in one place, adding indirection without earning it
+
+### Interface Design
+- Ignored inputs — functions that accept parameters they silently discard or never use
+- Misleading return shapes — return types that are technically correct but semantically wrong (e.g., returning an empty result on failure instead of signaling the failure)
+- Boolean flag parameters — a single function that behaves differently based on boolean arguments, conflating multiple behaviors behind one entry point
+- Unstable interfaces — public APIs whose shape will likely need to change, forcing callers to update when it does
+
+### Long-Term Cost Signals
+- Fragile inheritance — deep or wide class hierarchies where changing a base class risks breaking descendants
+- Dead code left reachable — unused functions, unreachable branches, or stale exports that remain importable
+- Unaddressed debt markers — TODO, FIXME, HACK, or similar annotations that indicate known problems left in place
+- Distant coupling — code that requires understanding modules far from the call site to modify safely
+
+## Severity Guide
+
+- **error**: Actively harmful to maintainability — will cause bugs or incorrect changes by the next person who edits nearby code (e.g., misleading name that inverts the reader's understanding, leaky abstraction that callers already work around)
+- **warning**: Significant maintainability cost that compounds over time (e.g., duplication across files, tight coupling, mixed responsibilities in a single function)
+- **info**: Improvement opportunity that would make the code easier to work with (e.g., extract helper, add clarifying comment, rename for consistency)
+
+## Out of Scope
+
+- Security vulnerabilities (handled by security agent)
+- Correctness or logic bugs (handled by correctness agent)
+- Code style or formatting (handled by linter)
+- Performance optimizations
+
+{output_instructions}