9thlevelsoftware/legion/code-polish

Input:
  phase_id     — current phase (optional, from STATE.md)
  file_path    — explicit file or glob (optional, from CLI arg)
  directory    — explicit directory (optional, from --scope=directory:<path>)
  scope_mode   — "changed" | "directory" | "auto" (default: "auto")
 
Step 1: Determine base file set
  If file_path provided:
    base_files = resolve glob or literal path → file list
  Else if phase_id provided:
    Read .planning/phases/phase-{N}-plan.md
    base_files = union of all files_modified across all plans in the phase
  Else if scope_mode == "directory" AND directory provided:
    base_files = all source files under directory (recursive)
  Else:
    Read .planning/STATE.md → find current phase → extract files_modified
    If no current phase or no files found:
      FAIL: "Cannot auto-detect scope. Provide --file, --phase, or --scope=directory:<path>"
 
Step 2: Expand to dependents (one level)
  If scope_mode == "changed":
    Skip this step entirely — polish only the base files
  Else:
    For each file in base_files:
      Parse its exports (named exports, default export, module.exports)
      Search project source files for import/require statements referencing this file
      Add importing files to expanded_set (one level only — do not recurse further)
    base_files = base_files ∪ expanded_set
 
Step 3: Apply scope overrides
  If scope_mode == "changed":
    Already handled in Step 2 (skip expansion)
  If scope_mode == "directory":
    Filter base_files to only files under the specified directory
 
Step 4: Filter excluded paths
  Remove files matching any of:
    **/node_modules/**
    **/dist/**
    **/build/**
    **/out/**
    **/.git/**
    **/.planning/**
    **/*.lock
    **/*.min.js
    **/*.min.css
    **/*.map
    Binary files (images, fonts, compiled assets)
    Files matching patterns in .gitignore
 
Step 5: Cap file count
  If len(base_files) > 50:
    Log WARNING: "Scope contains {N} files — capping at 50. Use --scope=changed or --file to narrow."
    Truncate to first 50 files (sorted by modification time, most recent first)
 
Step 6: Report
  Log: "Polish scope: {len(base_files)} files"
  Log: "  Base: {count_base} | Dependents: {count_expanded} | Excluded: {count_filtered}"
  Return base_files as ordered list

Input: base_files (from Section 1)
 
Step 1: Read explicit standards
  If CLAUDE.md exists at project root:
    Extract any sections about: naming, formatting, imports, comments, error handling
    Store as explicit_conventions (highest precedence)
 
Step 2: Read detected conventions
  If .planning/CODEBASE.md exists:
    Extract "Conventions" or "Patterns" sections
    Store as detected_conventions (medium precedence)
 
Step 3: Sample codebase for implicit conventions
  Select up to 10 files from base_files (prefer largest files by line count)
  For each sampled file, detect:
    naming_style:
      variables → camelCase | snake_case | PascalCase | SCREAMING_SNAKE
      functions → camelCase | snake_case | PascalCase
      files     → kebab-case | camelCase | snake_case | PascalCase
      constants → SCREAMING_SNAKE | camelCase | PascalCase
    import_style:
      ordering  → stdlib-first | third-party-first | grouped-by-type | unordered
      syntax    → named-only | default-preferred | mixed
      paths     → absolute | relative | aliases
    error_handling:
      pattern   → try-catch | Result-type | error-first-callback | .catch() | mix
      granularity → per-call | per-function | boundary-only
    comment_style:
      doc_format → JSDoc | TSDoc | docstring | Javadoc | XML-doc | none
      inline     → above-line | end-of-line | mixed | none
    function_style:
      declaration → function-keyword | arrow | mixed
      max_length  → median function length in lines
    string_style:
      quotes      → single | double | backtick-preferred
    trailing_commas: always | never | multiline-only
    semicolons:     always | never | asi
    file_structure:
      ordering    → imports-types-constants-functions-exports |
                     imports-constants-functions-exports |
                     unstructured
  Store as implicit_conventions (lowest precedence)
 
Step 4: Merge conventions
  Final convention set = explicit_conventions ⊕ detected_conventions ⊕ implicit_conventions
  Where ⊕ means: for each convention key, use the highest-precedence source that defines it
  If a convention is contradictory between sources, explicit wins. Log the conflict:
    "Convention conflict: {key} — explicit={value_a}, detected={value_b}. Using explicit."
 
Step 5: Report
  Log: "Detected conventions:"
  For each convention key with a resolved value:
    Log: "  {key}: {value} (source: {explicit|detected|implicit})"
  Return merged convention set

REMOVE — restates-code:
  BEFORE:
    // Set the user's name
    user.name = newName;
  AFTER:
    user.name = newName;
 
REMOVE — ai-narration:
  BEFORE:
    // First, we need to validate the input parameters to ensure they meet
    // the expected format before proceeding with the database query
    validateInput(params);
  AFTER:
    validateInput(params);
 
REMOVE — commented-out-code:
  BEFORE:
    // function oldApproach(data) {
    //   return data.map(x => x * 2);
    // }
    function newApproach(data) {
  AFTER:
    function newApproach(data) {
 
REMOVE — stale-todo:
  BEFORE:
    // TODO fix this later
    const result = fetchData();
  AFTER:
    const result = fetchData();
 
REMOVE — noise-divider:
  BEFORE:
    // ========================
    // Helper Functions
    // ========================
    function helper() {
  AFTER:
    function helper() {
 
REMOVE — signature-restatement:
  BEFORE:
    /**
     * Calculates the total price.
     * @param items - The items array
     * @returns The total price
     */
    function calculateTotalPrice(items: Item[]): number {
  AFTER:
    function calculateTotalPrice(items: Item[]): number {

For each removed comment, log:
  PASS1 | {file_path}:{line_number} | CLEAN | "{removed_text (first 80 chars)}" | {reason_code}
 
Example:
  PASS1 | src/auth/login.ts:42 | CLEAN | "// Set the username to the new value" | restates-code
  PASS1 | src/api/handler.ts:17 | CLEAN | "// Now we need to validate the request body befor..." | ai-narration

SIMPLIFY — guard-clause:
  BEFORE:
    function process(user) {
      if (user) {
        if (user.isActive) {
          return doWork(user);
        } else {
          return null;
        }
      } else {
        return null;
      }
    }
  AFTER:
    function process(user) {
      if (!user || !user.isActive) return null;
      return doWork(user);
    }
 
SIMPLIFY — lookup-table:
  BEFORE:
    function getStatusLabel(status) {
      if (status === 'active') return 'Active';
      if (status === 'pending') return 'Pending';
      if (status === 'closed') return 'Closed';
      return 'Unknown';
    }
  AFTER:
    const STATUS_LABELS = { active: 'Active', pending: 'Pending', closed: 'Closed' };
    function getStatusLabel(status) {
      return STATUS_LABELS[status] ?? 'Unknown';
    }
 
SIMPLIFY — dead-code:
  BEFORE:
    function validate(input) {
      if (!input) throw new Error('missing input');
      return input.trim();
      console.log('validated');  // unreachable
    }
  AFTER:
    function validate(input) {
      if (!input) throw new Error('missing input');
      return input.trim();
    }
 
SIMPLIFY — collapse-wrapper:
  BEFORE:
    function formatName(first, last) {
      return buildFullName(first, last);
    }
  AFTER:
    // Remove formatName entirely; replace call sites with buildFullName