@soulbatical/tetra-dev-toolkit 1.2.0 → 1.3.1

package/lib/checks/health/file-organization.js

@@ -0,0 +1,389 @@
+/**
+ * Health Check: File Organization (docs, scripts, config & code dir cleanliness)
+ *
+ * Verifies that:
+ * 1. Documentation files (.md) live in /docs/ or repo root
+ * 2. Scripts (.sh) live in /scripts/ or allowed dirs
+ * 3. Config files (.yml/.yaml) live in allowed locations
+ * 4. No nested docs/ directories exist
+ * 5. Code directories (backend/, frontend/, etc.) contain only code — no clutter
+ *
+ * Score: 6pt max
+ * - 1pt: No stray .md files outside /docs and root
+ * - 1pt: No stray .sh scripts outside allowed dirs
+ * - 1pt: No stray .yml/.yaml config files outside allowed dirs
+ * - 1pt: No nested docs/ directories
+ * - 1pt: No clutter in code directories (no .txt, .log, .pdf, .csv, .env, .bak, .tmp, .orig)
+ * - 1pt: No clutter in repo root (no .txt, .log, .pdf, .csv, .png, .jpg, tmp/, logs/, data/, venv/)
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'fs'
+import { join, relative, basename } from 'path'
+import { createCheck } from './types.js'
+
+const ALLOWED_ROOT_MD = new Set([
+  'readme.md', 'claude.md', 'changelog.md', 'license.md', 'license',
+  'prompt.md', 'plan.md', 'contributing.md', 'code_of_conduct.md'
+])
+
+const IGNORED_DIRS = new Set([
+  'node_modules', 'dist', 'build', '.git', '.next', '.cache', '.turbo',
+  'coverage', '.nyc_output', '.playwright', 'test-results'
+])
+
+const ALLOWED_SCRIPT_DIRS = new Set([
+  'scripts', 'shell', 'hooks', '.husky', '.ralph', '.claude'
+])
+
+/** Directories whose .md content is always allowed (tooling config) */
+const ALLOWED_MD_DIRS = new Set([
+  'docs', '.ralph', '.claude', '.agents', 'e2e'
+])
+
+/** Directories where .yml/.yaml config files are allowed */
+const ALLOWED_CONFIG_DIRS = new Set([
+  '.ralph', '.github', '.claude', '.circleci', '.gitlab'
+])
+
+/** Code directories that should only contain code */
+const CODE_DIRS = ['backend', 'frontend', 'backend-mcp', 'backend-pdf', 'mcp']
+
+/** File extensions that are clutter in code directories */
+const CLUTTER_EXTENSIONS = new Set([
+  '.txt', '.log', '.pdf', '.csv', '.bak', '.tmp', '.orig',
+  '.patch', '.diff', '.bk', '.old'
+])
+
+/** File names that are clutter in code directories (regardless of extension) */
+const CLUTTER_NAMES = new Set([
+  '.env', '.env.local', '.env.development', '.env.production', '.env.staging'
+])
+
+/** Files allowed in code dirs despite having clutter extensions */
+const ALLOWED_CLUTTER = new Set([
+  'robots.txt', 'llms.txt', 'llms-full.txt', 'humans.txt',
+  'security.txt', 'ads.txt', 'manifest.txt'
+])
+
+/** Subdirectories within code dirs where clutter files are OK */
+const ALLOWED_CLUTTER_SUBDIRS = new Set([
+  'public', 'static', 'assets', 'fixtures', 'test-fixtures',
+  'supabase', 'migrations', 'prisma'
+])
+
+/** File extensions that are clutter in the repo root */
+const ROOT_CLUTTER_EXTENSIONS = new Set([
+  '.txt', '.log', '.pdf', '.csv', '.png', '.jpg', '.jpeg', '.gif',
+  '.bak', '.tmp', '.orig', '.patch', '.diff', '.bk', '.old', '.py'
+])
+
+/**
+ * Root files that are allowed despite having clutter extensions.
+ * Standard tooling/platform configs that belong in root.
+ */
+const ALLOWED_ROOT_FILES = new Set([
+  // Platform configs
+  'dockerfile', 'dockerfile.bot', 'dockerfile.dev', 'dockerfile.prod',
+  'procfile', 'nixpacks.toml', 'netlify.toml', 'vercel.json', 'railway.json',
+  'render.yaml', 'fly.toml',
+  // JS/TS tooling
+  'components.json', 'ecosystem.config.js', 'ecosystem.config.cjs',
+  '.eslintrc.json', '.prettierrc', '.prettierrc.json',
+  'vitest.setup.ts', 'vitest.setup.js', 'jest.setup.ts', 'jest.setup.js',
+  'commitlint.config.js', 'lint-staged.config.js',
+  // Lock files
+  'bun.lockb', 'yarn.lock', 'pnpm-lock.yaml', 'deno.lock',
+])
+
+/** Root directories that are clutter (should not exist in repo root) */
+const ROOT_CLUTTER_DIRS = new Set([
+  'tmp', 'temp', 'logs', 'log', 'data', 'venv', '.venv',
+  'reports', 'output', 'out', 'backup', 'backups'
+])
+
+/**
+ * Recursively find files matching a predicate, respecting ignored dirs
+ */
+function findFiles(dir, predicate, maxDepth = 5, currentDepth = 0) {
+  const results = []
+  if (currentDepth >= maxDepth) return results
+
+  let entries
+  try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return results }
+
+  for (const entry of entries) {
+    const name = entry.name
+    if (IGNORED_DIRS.has(name)) continue
+
+    const fullPath = join(dir, name)
+    if (entry.isDirectory()) {
+      results.push(...findFiles(fullPath, predicate, maxDepth, currentDepth + 1))
+    } else if (entry.isFile() && predicate(name, fullPath)) {
+      results.push(fullPath)
+    }
+  }
+  return results
+}
+
+/** Directories that may contain a docs/ subdirectory (allowed, not flagged) */
+const ALLOWED_NESTED_DOCS_PARENTS = new Set(['.ralph'])
+
+/**
+ * Find directories named "docs" that are not at the repo root,
+ * excluding allowed parents like .ralph/docs
+ */
+function findNestedDocsDirs(rootPath, currentDir, maxDepth = 4, currentDepth = 0) {
+  const results = []
+  if (currentDepth >= maxDepth) return results
+
+  let entries
+  try { entries = readdirSync(currentDir, { withFileTypes: true }) } catch { return results }
+
+  for (const entry of entries) {
+    const name = entry.name
+    if (IGNORED_DIRS.has(name)) continue
+    if (!entry.isDirectory()) continue
+
+    const fullPath = join(currentDir, name)
+    const relFromRoot = relative(rootPath, fullPath)
+    const topDir = relFromRoot.split('/')[0]
+
+    if (name === 'docs' && currentDepth > 0) {
+      // Skip if parent is an allowed directory (e.g., .ralph/docs)
+      if (!ALLOWED_NESTED_DOCS_PARENTS.has(topDir)) {
+        results.push(fullPath)
+      }
+    } else {
+      results.push(...findNestedDocsDirs(rootPath, fullPath, maxDepth, currentDepth + 1))
+    }
+  }
+  return results
+}
+
+export async function check(projectPath) {
+  const result = createCheck('file-organization', 6, {
+    strayMdFiles: [],
+    strayScripts: [],
+    strayConfigs: [],
+    clutterFiles: [],
+    rootClutter: [],
+    nestedDocsDirs: [],
+    totalStrayMd: 0,
+    totalStrayScripts: 0,
+    totalStrayConfigs: 0,
+    totalClutter: 0,
+    totalRootClutter: 0,
+    totalNestedDocs: 0
+  })
+
+  // Load .gitignore entries for root clutter check
+  const gitignorePath = join(projectPath, '.gitignore')
+  const gitignoredDirs = new Set()
+  if (existsSync(gitignorePath)) {
+    try {
+      const lines = readFileSync(gitignorePath, 'utf-8').split('\n')
+        .map(l => l.trim()).filter(l => l && !l.startsWith('#'))
+      for (const line of lines) {
+        // Match dir entries like "tmp/" or "tmp"
+        const cleaned = line.replace(/\/$/, '')
+        if (cleaned) gitignoredDirs.add(cleaned)
+      }
+    } catch { /* ignore */ }
+  }
+
+  // --- Check 1: Stray .md files ---
+  const allMdFiles = findFiles(projectPath, (name) => name.endsWith('.md'))
+  const strayMd = []
+
+  for (const file of allMdFiles) {
+    const rel = relative(projectPath, file)
+    const parts = rel.split('/')
+
+    // README.md and CLAUDE.md are always allowed, anywhere
+    const nameLc = basename(file).toLowerCase()
+    if (nameLc === 'readme.md' || nameLc === 'claude.md') continue
+
+    // Root .md files: only allowed ones
+    if (parts.length === 1) {
+      if (ALLOWED_ROOT_MD.has(basename(file).toLowerCase())) continue
+      strayMd.push(rel)
+      continue
+    }
+
+    // Inside allowed top-level directories: always OK
+    if (ALLOWED_MD_DIRS.has(parts[0])) continue
+
+    // Inside shell/templates: OK (Ralph templates)
+    if (parts[0] === 'shell' && parts[1] === 'templates') continue
+
+    // Everything else is stray
+    strayMd.push(rel)
+  }
+
+  result.details.strayMdFiles = strayMd.slice(0, 20) // Cap at 20 for readability
+  result.details.totalStrayMd = strayMd.length
+
+  // --- Check 2: Stray scripts ---
+  const allScripts = findFiles(projectPath, (name) => name.endsWith('.sh'))
+  const strayScripts = []
+
+  for (const file of allScripts) {
+    const rel = relative(projectPath, file)
+    const parts = rel.split('/')
+    const topDir = parts[0]
+
+    // Root-level scripts: OK
+    if (parts.length === 1) continue
+
+    // Inside allowed script directories: OK
+    if (ALLOWED_SCRIPT_DIRS.has(topDir)) continue
+
+    // Everything else is stray
+    strayScripts.push(rel)
+  }
+
+  result.details.strayScripts = strayScripts.slice(0, 20)
+  result.details.totalStrayScripts = strayScripts.length
+
+  // --- Check 3: Stray config files (.yml/.yaml) ---
+  const allConfigs = findFiles(projectPath, (name) => name.endsWith('.yml') || name.endsWith('.yaml'))
+  const strayConfigs = []
+
+  for (const file of allConfigs) {
+    const rel = relative(projectPath, file)
+    const parts = rel.split('/')
+
+    // Root-level configs: always OK (doppler.yaml, .coderabbit.yaml, etc.)
+    if (parts.length === 1) continue
+
+    // Inside allowed config directories: OK
+    if (ALLOWED_CONFIG_DIRS.has(parts[0])) continue
+
+    // Everything else is stray
+    strayConfigs.push(rel)
+  }
+
+  result.details.strayConfigs = strayConfigs.slice(0, 20)
+  result.details.totalStrayConfigs = strayConfigs.length
+
+  // --- Check 4: Clutter in code directories ---
+  const clutterFiles = []
+
+  for (const codeDir of CODE_DIRS) {
+    const codePath = join(projectPath, codeDir)
+    let dirExists
+    try { readdirSync(codePath); dirExists = true } catch { dirExists = false }
+    if (!dirExists) continue
+
+    const allFiles = findFiles(codePath, () => true)
+    for (const file of allFiles) {
+      const name = basename(file).toLowerCase()
+      const rel = relative(projectPath, file)
+      const relFromCodeDir = relative(codePath, file)
+      const subParts = relFromCodeDir.split('/')
+
+      // Check if in an allowed subdirectory (public/, supabase/migrations/, etc.)
+      if (subParts.length > 1 && ALLOWED_CLUTTER_SUBDIRS.has(subParts[0])) continue
+
+      // Check for .env files (secrets!)
+      if (CLUTTER_NAMES.has(name)) {
+        clutterFiles.push(rel)
+        continue
+      }
+
+      // Check for allowed files (robots.txt in public, etc.)
+      if (ALLOWED_CLUTTER.has(name)) continue
+
+      // Check extension
+      const ext = name.includes('.') ? '.' + name.split('.').pop() : ''
+      if (CLUTTER_EXTENSIONS.has(ext)) {
+        // .env.example and .env.test are OK (templates)
+        if (name.endsWith('.example') || name.endsWith('.test')) continue
+        clutterFiles.push(rel)
+      }
+    }
+  }
+
+  result.details.clutterFiles = clutterFiles.slice(0, 20)
+  result.details.totalClutter = clutterFiles.length
+
+  // --- Check 5: Root clutter (files & directories) ---
+  const rootClutter = []
+
+  let rootEntries
+  try { rootEntries = readdirSync(projectPath, { withFileTypes: true }) } catch { rootEntries = [] }
+
+  for (const entry of rootEntries) {
+    const name = entry.name
+    const nameLower = name.toLowerCase()
+
+    if (entry.isDirectory()) {
+      // Check for clutter directories in root (skip if already gitignored)
+      if (ROOT_CLUTTER_DIRS.has(nameLower) && !gitignoredDirs.has(name) && !gitignoredDirs.has(nameLower)) {
+        rootClutter.push(name + '/')
+      }
+      continue
+    }
+
+    if (!entry.isFile()) continue
+
+    // Skip dotfiles that are standard config (.gitignore, .eslintrc, .env.example, etc.)
+    if (name.startsWith('.')) continue
+
+    // Skip known allowed root files
+    if (ALLOWED_ROOT_FILES.has(nameLower)) continue
+
+    // Skip package manifests, lockfiles, configs (handled by other checks or standard)
+    if (nameLower.endsWith('.json') || nameLower.endsWith('.mjs') || nameLower.endsWith('.cjs')) continue
+    if (nameLower.endsWith('.toml') || nameLower.endsWith('.lock')) continue
+    if (nameLower.endsWith('.md')) continue // Handled by check 1
+    if (nameLower.endsWith('.sh')) continue // Handled by check 2
+    if (nameLower.endsWith('.yml') || nameLower.endsWith('.yaml')) continue // Handled by check 3
+    if (nameLower.endsWith('.ts') || nameLower.endsWith('.js')) continue // Config files like vitest.setup.ts
+
+    // Check for clutter extensions
+    const ext = nameLower.includes('.') ? '.' + nameLower.split('.').pop() : ''
+    if (ROOT_CLUTTER_EXTENSIONS.has(ext)) {
+      rootClutter.push(name)
+    }
+  }
+
+  result.details.rootClutter = rootClutter.slice(0, 20)
+  result.details.totalRootClutter = rootClutter.length
+
+  // --- Check 6: Nested docs/ directories ---
+  const nestedDocs = findNestedDocsDirs(projectPath, projectPath)
+  const nestedDocsRel = nestedDocs.map(d => relative(projectPath, d))
+
+  result.details.nestedDocsDirs = nestedDocsRel
+  result.details.totalNestedDocs = nestedDocsRel.length
+
+  // --- Scoring ---
+  let score = 6
+
+  if (strayMd.length > 0) score -= 1
+  if (strayScripts.length > 0) score -= 1
+  if (strayConfigs.length > 0) score -= 1
+  if (clutterFiles.length > 0) score -= 1
+  if (rootClutter.length > 0) score -= 1
+  if (nestedDocsRel.length > 0) score -= 1
+
+  result.score = score
+
+  if (score === 6) {
+    result.status = 'ok'
+    result.details.message = 'Clean repo: docs in /docs, scripts in /scripts, root & code dirs clean'
+  } else {
+    result.status = score >= 5 ? 'warning' : 'error'
+    const issues = []
+    if (strayMd.length > 0) issues.push(`${strayMd.length} stray .md`)
+    if (strayScripts.length > 0) issues.push(`${strayScripts.length} stray .sh`)
+    if (strayConfigs.length > 0) issues.push(`${strayConfigs.length} stray .yml`)
+    if (clutterFiles.length > 0) issues.push(`${clutterFiles.length} clutter in code dirs`)
+    if (rootClutter.length > 0) issues.push(`${rootClutter.length} root clutter`)
+    if (nestedDocsRel.length > 0) issues.push(`${nestedDocsRel.length} nested docs/`)
+    result.details.message = issues.join(', ')
+  }
+
+  return result
+}

package/lib/checks/health/index.js

@@ -1,5 +1,5 @@
 /**
- * Health Checks — All 15 project health checks
+ * Health Checks — All 16 project health checks
  *
  * Main entry: scanProjectHealth(projectPath, projectName, options?)
  * Individual checks available via named imports.
@@ -24,3 +24,5 @@ export { check as checkStellaIntegration } from './stella-integration.js'
 export { check as checkClaudeMd } from './claude-md.js'
 export { check as checkDopplerCompliance } from './doppler-compliance.js'
 export { check as checkInfrastructureYml } from './infrastructure-yml.js'
+export { check as checkFileOrganization } from './file-organization.js'
+export { check as checkRpcParamMismatch } from './rpc-param-mismatch.js'

package/lib/checks/health/rpc-param-mismatch.js

@@ -0,0 +1,92 @@
+/**
+ * Health Check: RPC Parameter Mismatch
+ *
+ * Compares .rpc() calls in TypeScript with SQL function definitions
+ * to detect parameter name mismatches that cause PGRST202 runtime errors.
+ *
+ * Score: 3 (full) with deductions:
+ *   - Critical mismatch (extra param in TS): -1.5 per finding (max -3)
+ *   - Low (missing params): -0.25 per finding (max -1)
+ */
+
+import { createCheck } from './types.js'
+import { run as runAuditCheck } from '../supabase/rpc-param-mismatch.js'
+
+export async function check(projectPath) {
+  const result = createCheck('rpc-param-mismatch', 3, {
+    sqlFunctionsFound: 0,
+    rpcCallsFound: 0,
+    rpcCallsChecked: 0,
+    criticalMismatches: [],
+    missingParams: [],
+    message: ''
+  })
+  result.score = 3 // Start full, deduct for issues
+
+  // Re-use the audit check with default config paths
+  const config = {
+    paths: {
+      backend: ['backend/src', 'src'],
+      migrations: ['supabase/migrations', 'backend/supabase/migrations', 'migrations']
+    }
+  }
+
+  let auditResult
+  try {
+    auditResult = await runAuditCheck(config, projectPath)
+  } catch {
+    result.details.message = 'Failed to run RPC param mismatch check'
+    return result
+  }
+
+  if (auditResult.skipped) {
+    result.score = 3
+    result.details.message = auditResult.skipReason || 'Skipped'
+    return result
+  }
+
+  result.details.sqlFunctionsFound = auditResult.details.sqlFunctionsFound
+  result.details.rpcCallsFound = auditResult.details.rpcCallsFound
+  result.details.rpcCallsChecked = auditResult.details.rpcCallsChecked
+
+  // Process findings
+  const criticals = auditResult.findings.filter(f => f.severity === 'critical')
+  const lows = auditResult.findings.filter(f => f.severity === 'low')
+
+  result.details.criticalMismatches = criticals.map(f => ({
+    file: f.file,
+    line: f.line,
+    function: f.rpcFunction,
+    extraParams: f.extraInTs,
+    expectedParams: f.sqlParams
+  }))
+
+  result.details.missingParams = lows.map(f => ({
+    file: f.file,
+    line: f.line,
+    function: f.rpcFunction,
+    tsParamCount: f.tsParams?.length,
+    sqlParamCount: f.sqlParams?.length
+  }))
+
+  // Score deductions
+  if (criticals.length > 0) {
+    const deduction = Math.min(3, criticals.length * 1.5)
+    result.score -= deduction
+    result.status = 'error'
+    result.details.message = `${criticals.length} RPC parameter mismatch(es) — will cause PGRST202 runtime errors`
+  }
+
+  if (lows.length > 0 && result.status === 'ok') {
+    const deduction = Math.min(1, lows.length * 0.25)
+    result.score -= deduction
+    if (result.status === 'ok' && lows.length > 5) result.status = 'warning'
+  }
+
+  if (result.status === 'ok') {
+    result.details.message = `${auditResult.details.rpcCallsChecked} RPC calls verified against SQL definitions`
+  }
+
+  result.score = Math.max(0, result.score)
+  return result
+}

package/lib/checks/health/scanner.js

@@ -1,7 +1,7 @@
 /**
  * Project Health Scanner
  *
- * Orchestrates all 15 health checks and produces a HealthReport.
+ * Orchestrates all 16 health checks and produces a HealthReport.
  * This is the main entry point — consumers call scanProjectHealth().
  */
 
@@ -20,6 +20,8 @@ import { check as checkStellaIntegration } from './stella-integration.js'
 import { check as checkClaudeMd } from './claude-md.js'
 import { check as checkDopplerCompliance } from './doppler-compliance.js'
 import { check as checkInfrastructureYml } from './infrastructure-yml.js'
+import { check as checkFileOrganization } from './file-organization.js'
+import { check as checkRpcParamMismatch } from './rpc-param-mismatch.js'
 import { calculateHealthStatus } from './types.js'
 
 /**
@@ -48,7 +50,9 @@ export async function scanProjectHealth(projectPath, projectName, options = {})
     checkStellaIntegration(projectPath),
     checkClaudeMd(projectPath),
     checkDopplerCompliance(projectPath),
-    checkInfrastructureYml(projectPath)
+    checkInfrastructureYml(projectPath),
+    checkFileOrganization(projectPath),
+    checkRpcParamMismatch(projectPath)
   ])
 
   const totalScore = checks.reduce((sum, c) => sum + c.score, 0)

package/lib/checks/health/stella-integration.js

@@ -1,7 +1,7 @@
 /**
- * Health Check: @ralph/stella Integration
+ * Health Check: @soulbatical/stella Integration
  *
- * Checks for @ralph/stella dependency and integration level in MCP server.
+ * Checks for @soulbatical/stella dependency and integration level in MCP server.
  * Score: 0 = not installed, 1 = basic, 2 = full integration
  */
 
@@ -14,7 +14,7 @@ export async function check(projectPath) {
     installed: false, version: null, integrationLevel: 'none', features: [], packageLocation: null
   })
 
-  // Search for @ralph/stella in package.json files
+  // Search for @soulbatical/stella in package.json files
   const packageLocations = [
     { path: join(projectPath, 'package.json'), label: 'root' },
     { path: join(projectPath, 'mcp', 'package.json'), label: 'mcp/' },
@@ -29,8 +29,8 @@ export async function check(projectPath) {
     try {
       const pkg = JSON.parse(readFileSync(loc.path, 'utf-8'))
       const allDeps = { ...pkg.dependencies, ...pkg.devDependencies }
-      if (allDeps['@ralph/stella']) {
-        stellaDep = allDeps['@ralph/stella']
+      if (allDeps['@soulbatical/stella']) {
+        stellaDep = allDeps['@soulbatical/stella']
         stellaLocation = loc.label
         break
       }
@@ -50,8 +50,8 @@ export async function check(projectPath) {
 
   // Get installed version
   const nmPaths = [
-    join(projectPath, 'node_modules', '@ralph', 'stella', 'package.json'),
-    join(projectPath, stellaLocation || '', 'node_modules', '@ralph', 'stella', 'package.json'),
+    join(projectPath, 'node_modules', '@soulbatical', 'stella', 'package.json'),
+    join(projectPath, stellaLocation || '', 'node_modules', '@soulbatical', 'stella', 'package.json'),
   ]
   for (const nmPath of nmPaths) {
     if (!existsSync(nmPath)) continue

package/lib/checks/health/types.js

@@ -5,7 +5,7 @@
  */
 
 /**
- * @typedef {'plugins'|'mcps'|'git'|'tests'|'secrets'|'quality-toolkit'|'naming-conventions'|'rls-audit'|'gitignore'|'repo-visibility'|'vincifox-widget'|'stella-integration'|'claude-md'|'doppler-compliance'|'infrastructure-yml'} HealthCheckType
+ * @typedef {'plugins'|'mcps'|'git'|'tests'|'secrets'|'quality-toolkit'|'naming-conventions'|'rls-audit'|'rpc-param-mismatch'|'gitignore'|'repo-visibility'|'vincifox-widget'|'stella-integration'|'claude-md'|'doppler-compliance'|'infrastructure-yml'|'file-organization'} HealthCheckType
  *
  * @typedef {'ok'|'warning'|'error'} HealthStatus
  *
@@ -66,7 +66,7 @@ export function calculateHealthStatus(checks) {
 
   // Critical checks override percentage
   if (checks.some(c =>
-    (c.type === 'secrets' || c.type === 'rls-audit' || c.type === 'repo-visibility') && c.status === 'error'
+    (c.type === 'secrets' || c.type === 'rls-audit' || c.type === 'rpc-param-mismatch' || c.type === 'repo-visibility') && c.status === 'error'
   )) {
     return 'unhealthy'
   }

package/lib/checks/hygiene/file-organization.js

@@ -0,0 +1,105 @@
+/**
+ * Hygiene Check: File Organization
+ *
+ * Wraps the health check file-organization as a tetra-audit check.
+ * Detects stray docs, scripts, clutter in code dirs, and root mess.
+ *
+ * Severity: high — messy repos ship messy code
+ */
+
+import { check as healthCheck } from '../health/file-organization.js'
+
+export const meta = {
+  id: 'file-organization',
+  name: 'File Organization',
+  category: 'hygiene',
+  severity: 'high',
+  description: 'Checks that docs are in /docs, scripts in /scripts, no clutter in code dirs or repo root'
+}
+
+export async function run(config, projectRoot) {
+  const result = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
+    details: {}
+  }
+
+  const health = await healthCheck(projectRoot)
+  result.details = health.details
+
+  // Convert health check results to findings
+  if (health.details.totalStrayMd > 0) {
+    result.findings.push({
+      type: 'Stray documentation files',
+      severity: 'high',
+      message: `${health.details.totalStrayMd} .md file(s) outside /docs/ — move to docs/ or delete`,
+      files: health.details.strayMdFiles
+    })
+    result.summary.high++
+    result.summary.total++
+  }
+
+  if (health.details.totalStrayScripts > 0) {
+    result.findings.push({
+      type: 'Stray shell scripts',
+      severity: 'medium',
+      message: `${health.details.totalStrayScripts} .sh file(s) outside /scripts/ — move to scripts/`,
+      files: health.details.strayScripts
+    })
+    result.summary.medium++
+    result.summary.total++
+  }
+
+  if (health.details.totalStrayConfigs > 0) {
+    result.findings.push({
+      type: 'Stray config files',
+      severity: 'low',
+      message: `${health.details.totalStrayConfigs} .yml/.yaml file(s) outside allowed dirs`,
+      files: health.details.strayConfigs
+    })
+    result.summary.low++
+    result.summary.total++
+  }
+
+  if (health.details.totalClutter > 0) {
+    // Clutter in code dirs is high — often includes .env secrets
+    const hasEnv = health.details.clutterFiles.some(f => f.includes('.env'))
+    const severity = hasEnv ? 'critical' : 'high'
+    result.findings.push({
+      type: 'Clutter in code directories',
+      severity,
+      message: `${health.details.totalClutter} clutter file(s) in code dirs (${hasEnv ? 'includes .env!' : '.txt, .log, .bak, etc.'})`,
+      files: health.details.clutterFiles
+    })
+    result.summary[severity]++
+    result.summary.total++
+  }
+
+  if (health.details.totalRootClutter > 0) {
+    result.findings.push({
+      type: 'Root clutter',
+      severity: 'high',
+      message: `${health.details.totalRootClutter} clutter item(s) in repo root — ${health.details.rootClutter.join(', ')}`,
+      files: health.details.rootClutter
+    })
+    result.summary.high++
+    result.summary.total++
+  }
+
+  if (health.details.totalNestedDocs > 0) {
+    result.findings.push({
+      type: 'Nested docs/ directories',
+      severity: 'medium',
+      message: `${health.details.totalNestedDocs} nested docs/ dir(s) — consolidate into root /docs/`,
+      files: health.details.nestedDocsDirs
+    })
+    result.summary.medium++
+    result.summary.total++
+  }
+
+  // Fail if any high+ findings
+  result.passed = result.summary.critical === 0 && result.summary.high === 0
+
+  return result
+}