@soulbatical/tetra-dev-toolkit 1.1.1 → 1.3.0

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

@@ -24,3 +24,4 @@ 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'

package/lib/checks/health/quality-toolkit.js

@@ -1,5 +1,5 @@
 /**
- * Health Check: @vca/dev-toolkit Installation
+ * Health Check: @soulbatical/tetra-dev-toolkit Installation
  *
  * Checks if the quality toolkit is installed and CLI commands available.
  * Score: 0 = not installed, 1 = installed, 2 = all commands available
@@ -15,7 +15,7 @@ export async function check(projectPath, { getCachedCodeQuality } = {}) {
   const result = createCheck('quality-toolkit', 2, {
     installed: false,
     version: null,
-    commands: { 'vca-audit': false, 'vca-setup': false, 'vca-dev-token': false }
+    commands: { 'tetra-audit': false, 'tetra-setup': false, 'tetra-dev-token': false }
   })
 
   const packageJsonPath = join(projectPath, 'package.json')
@@ -28,12 +28,12 @@ export async function check(projectPath, { getCachedCodeQuality } = {}) {
   try {
     const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'))
     const allDeps = { ...pkg.dependencies, ...pkg.devDependencies }
-    const toolkitDep = allDeps['@vca/dev-toolkit'] || allDeps['@vca/quality-toolkit']
+    const toolkitDep = allDeps['@soulbatical/tetra-dev-toolkit'] || allDeps['@vca/dev-toolkit'] || allDeps['@vca/quality-toolkit']
 
     if (!toolkitDep) {
       result.status = 'warning'
       result.details.message = 'Not installed'
-      result.details.installCommand = 'npm install --save-dev /Users/albertbarth/projecten/vca-quality-toolkit'
+      result.details.installCommand = 'npm install --save-dev @soulbatical/tetra-dev-toolkit'
       return result
     }
 
@@ -42,8 +42,12 @@ export async function check(projectPath, { getCachedCodeQuality } = {}) {
     result.score = 1
 
     // Get installed version from node_modules
-    for (const pkgName of ['dev-toolkit', 'quality-toolkit']) {
-      const toolkitPackagePath = join(projectPath, 'node_modules', '@vca', pkgName, 'package.json')
+    const lookupPaths = [
+      join(projectPath, 'node_modules', '@soulbatical', 'tetra-dev-toolkit', 'package.json'),
+      join(projectPath, 'node_modules', '@vca', 'dev-toolkit', 'package.json'),
+      join(projectPath, 'node_modules', '@vca', 'quality-toolkit', 'package.json'),
+    ]
+    for (const toolkitPackagePath of lookupPaths) {
       if (existsSync(toolkitPackagePath)) {
         try {
           result.details.version = JSON.parse(readFileSync(toolkitPackagePath, 'utf-8')).version
@@ -54,9 +58,9 @@ export async function check(projectPath, { getCachedCodeQuality } = {}) {
       }
     }
 
-    // Check CLI commands
+    // Check CLI commands (check new tetra-* names, fall back to legacy vca-*)
     const binPath = join(projectPath, 'node_modules', '.bin')
-    const commands = ['vca-audit', 'vca-setup', 'vca-dev-token']
+    const commands = ['tetra-audit', 'tetra-setup', 'tetra-dev-token']
     for (const cmd of commands) {
       result.details.commands[cmd] = existsSync(join(binPath, cmd))
     }

package/lib/checks/health/repo-visibility.js

@@ -43,7 +43,7 @@ export async function check(projectPath) {
 
   try {
     const response = await fetch(`https://api.github.com/repos/${owner}/${repo}`, {
-      headers: { 'User-Agent': 'vca-health-check' },
+      headers: { 'User-Agent': 'tetra-health-check' },
       signal: AbortSignal.timeout(5000)
     })
 

package/lib/checks/health/scanner.js

@@ -20,6 +20,7 @@ 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 { calculateHealthStatus } from './types.js'
 
 /**
@@ -48,7 +49,8 @@ export async function scanProjectHealth(projectPath, projectName, options = {})
     checkStellaIntegration(projectPath),
     checkClaudeMd(projectPath),
     checkDopplerCompliance(projectPath),
-    checkInfrastructureYml(projectPath)
+    checkInfrastructureYml(projectPath),
+    checkFileOrganization(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'|'gitignore'|'repo-visibility'|'vincifox-widget'|'stella-integration'|'claude-md'|'doppler-compliance'|'infrastructure-yml'|'file-organization'} HealthCheckType
  *
  * @typedef {'ok'|'warning'|'error'} HealthStatus
  *

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
+}

package/lib/checks/index.js

@@ -13,5 +13,9 @@ export * as huskyHooks from './stability/husky-hooks.js'
 export * as ciPipeline from './stability/ci-pipeline.js'
 export * as npmAudit from './stability/npm-audit.js'
 
+// Supabase checks
+export * as rlsPolicyAudit from './supabase/rls-policy-audit.js'
+export * as rpcParamMismatch from './supabase/rpc-param-mismatch.js'
+
 // Health checks (project ecosystem)
 export * as health from './health/index.js'

package/lib/checks/stability/ci-pipeline.js

@@ -91,7 +91,7 @@ export async function run(config, projectRoot) {
     },
     {
       name: 'security-audit',
-      patterns: ['npm audit', 'vca-audit', 'security-check', 'snyk', 'CodeQL'],
+      patterns: ['npm audit', 'tetra-audit', 'security-check', 'snyk', 'CodeQL'],
       severity: 'medium'
     }
   ]

package/lib/checks/stability/husky-hooks.js

@@ -56,7 +56,7 @@ export async function run(config, projectRoot) {
     { name: 'lint', patterns: ['lint', 'eslint'] },
     { name: 'type-check', patterns: ['tsc', 'typecheck', 'type-check'] },
     { name: 'test', patterns: ['test', 'jest', 'vitest'] },
-    { name: 'security', patterns: ['security', 'audit', 'vca-'] }
+    { name: 'security', patterns: ['security', 'audit', 'tetra-', 'vca-'] }
   ]
 
   const missingChecks = []