ln-637-test-structure-auditor

What this skill does

> **Paths:** File paths (`references/`, `../ln-*`) are relative to this skill directory.

# Maintainability/Structure Auditor (L3 Worker)

**Type:** L3 Worker

Specialized worker auditing test file organization, orphan tests, fragmented duplicates, and layout drift for maintainability as the test suite grows.

## Purpose & Scope

- Audit **Test Maintainability/Structure** (Category 8: Medium Priority)
- Detect layout pattern (flat / mirrored / co-located / hybrid)
- Flag flat directories exceeding growth thresholds with domain grouping recommendations
- Verify test-to-source mapping consistency, orphaned tests, and fragmented duplicates
- Emit `MOVE`, `MERGE`, or `DELETE_ORPHAN`
- Calculate compliance score (X/10)

## Inputs

**MANDATORY READ:** Load `references/audit_worker_core_contract.md`.

Receives `contextStore` with: `tech_stack`, `testFilesMetadata` (ALL types -- both automated and manual), `codebase_root`, `output_dir`, `domain_mode`, `all_domains`.

**Note:** Unlike other workers that receive type-filtered metadata, this worker receives ALL test files because directory structure analysis requires the full picture of where both automated and manual tests are placed.

## Workflow

Detection policy: use two-layer detection (candidate scan, then context verification); load `references/two_layer_detection.md` only when the verification method is ambiguous.

1) **Parse Context:** Extract test file list, output_dir, codebase_root, domain info from contextStore
2) **Map Source Structure:** Glob source directories (`src/`, `app/`, `lib/`) to build source domain/module tree
3) **Map Test Structure:** Group test files by parent directory, count files per directory, classify locations
4) **Scan Checks (Layer 1):** Run 6 audit checks (see Audit Rules) using Glob/Grep patterns
5) **Context Analysis (Layer 2 -- MANDATORY):** For each candidate finding, apply Layer 2 filters (see each check)
6) **Collect Findings:** Record violations with severity, location, effort, action, recommendation
7) **Calculate Score:** Count violations by severity, calculate compliance score (X/10)
8) **Write Report:** Build full markdown report in memory per `references/templates/audit_worker_report_template.md`, write to `{output_dir}/ln-637--global.md` in single Write call
9) **Return Summary:** Return minimal summary to coordinator (see Output Format)

## Audit Rules

### 1. Layout Pattern Detection

**What:** Detect which test organization pattern the project uses and check for unintentional mixing

**Detection:**
- Classify each test file location:
  - **Co-located:** test file in same directory as source file (e.g., `src/users/users.test.ts`)
  - **Mirrored:** test file in parallel hierarchy (e.g., `tests/users/users.test.ts` mirrors `src/users/`)
  - **Centralized-flat:** all tests in single directory (e.g., `tests/` or `__tests__/`)
  - **Manual:** files in `tests/manual/` (informational, not flagged)
- Calculate distribution percentages across patterns
- If >70% files follow one pattern -> that is the dominant pattern
- If no pattern reaches 70% -> hybrid

**Layer 2:**
- Hybrid is acceptable if different test TYPES use different patterns (e.g., unit tests co-located + integration tests in `tests/automated/integration/`). Check if deviation correlates with test type
- Projects with <5 test files -> skip (too small to establish pattern)

**Severity:** **MEDIUM** if hybrid without clear type-based rule (>30% of same-type tests deviate from dominant pattern)

**Recommendation:** Standardize test placement -- choose one pattern per test type and document in testing guidelines
**Action:** `MOVE`

**Effort:** L

### 2. Test-to-Source Mapping

**What:** Detect orphaned test files (source file deleted but test remains) and mismatched paths

**Detection:**
- For each test file, extract the implied source module:
  - `users.test.ts` -> `users.ts` or `users/index.ts`
  - `test_payments.py` -> `payments.py`
- Check if the implied source file exists in the expected location
- If source file not found -> orphaned test candidate

**Layer 2:**
- Skip integration/e2e tests (test multiple modules, no 1:1 source mapping)
- Skip tests in centralized-flat layout (no path-based mapping expected)
- Skip test files that import from multiple source modules (integration tests by nature)
- Skip utility/helper test files (`test_utils.ts`, `test_helpers.py`)

**Severity:** **MEDIUM** for orphaned tests (dead code), **LOW** for path mismatches

**Recommendation:** Delete orphaned tests or update to match current source structure
**Action:** `DELETE_ORPHAN` when the source behavior no longer exists; otherwise `MOVE`

**Effort:** S

### 3. Flat Directory Growth

**What:** Detect test directories with excessive file count that would benefit from subdirectory grouping

**Detection:**
- Count test files per directory (excluding `node_modules`, `dist`, `build`)
- Thresholds:
  - 15-20 files in one flat directory -> LOW (approaching limit)
  - \>20 files in one flat directory -> MEDIUM (restructure recommended)
- For MEDIUM findings, suggest domain-based grouping by analyzing file name prefixes:
  - Group by common prefix (e.g., `test_auth_*.py` -> `auth/` subdirectory)
  - Cross-reference with source domain structure if available

**Layer 2:**
- Skip if directory already has subdirectories (partially organized)
- Skip if files use clear naming prefixes that provide sufficient organization without subdirectories
- Skip `tests/manual/` (manual test structure has separate conventions)

**Severity:** **MEDIUM** (>20 files), **LOW** (15-20 files)

**Recommendation:** Group tests into subdirectories by domain/feature. Suggest specific grouping based on file name analysis:
```
# Before (flat):
tests/test_auth_login.py, tests/test_auth_tokens.py, tests/test_users_crud.py, ...

# After (grouped):
tests/auth/test_login.py, tests/auth/test_tokens.py, tests/users/test_crud.py, ...
```

**Effort:** M
**Action:** `MOVE`

### 4. Domain Grouping Alignment

**What:** Check whether test directory grouping mirrors source domain structure

**Detection:**
- Compare source domain directories (from `all_domains` or scanned `src/`) with test directory names
- For each source domain, check if a corresponding test group exists:
  - Mirrored layout: `tests/{domain}/` directory exists
  - Co-located: test files exist in `src/{domain}/`
- Flag source domains with zero corresponding test groups

**Layer 2:**
- Skip if project has no clear domain structure (`domain_mode="global"` or <2 source domains)
- Skip references/common/utils domains (cross-cutting, may not need dedicated test group)
- Skip if project uses centralized-flat layout (no grouping expected)

**Severity:** **MEDIUM** for domains with >5 source files but no test group, **LOW** otherwise

**Recommendation:** Create test directory/group for domain to maintain structural alignment

**Effort:** M
**Action:** `MOVE`

### 5. Co-location Consistency

**What:** Detect which co-location pattern the project uses and flag inconsistencies

**Detection:**
- Count test files placed next to source files vs. in dedicated test directories
- Calculate ratio: co-located / (co-located + centralized)
- If ratio 0.0-0.2 -> centralized pattern
- If ratio 0.8-1.0 -> co-located pattern
- If ratio 0.2-0.8 -> mixed (potential inconsistency)
- For mixed: identify which modules deviate from the dominant pattern

**Layer 2:**
- Mixed is acceptable if different test types use different placement:
  - Unit tests co-located + integration/e2e tests centralized -> valid hybrid
  - Check test file naming/location correlation with type
- Projects with <5 test files -> skip

**Severity:** **MEDIUM** if >20% of same-type tests deviate from dominant placement pattern

**Recommendation:** Consolidate test placement -- move deviating tests to follow the project's dominant pattern

**Effort:** M-L
**Action:** `MOVE`

### 6. Fragmented Duplicates

**What:** Detect duplicate or near-duplicate tests scattered acr