Mault AI-Assisted Code Quality Extension

Automate architectural discipline for AI-assisted development.

Fully tested with TypeScript, JavaScript, Python. Pro step templates available for Go, Rust, Java, .NET, C++, Swift, Julia (AI-generated, not yet fully tested)
Best for new -or- early projects
17 deterministic pattern detectors for clean code
Context-rich prompts for any AI coding assistant
Local-first with optional network-enabled features (e.g., dependency health analysis). Tool-agnostic (works with Cursor, Copilot, ChatGPT, Claude)
Core FREE forever | Pro: $99 activation + $7.99/month

Mault is designed as a local-first VS Code extension. While most analysis runs entirely on your machine, certain features (such as dependency health checks) may perform network requests to retrieve external metadata. See Data & Privacy Disclosure for details.

Ready to upgrade? Purchase Pro ($99)

How It Works

Mault Core (FREE)

Mault Core is easy to set up and monitors your workspace, surfacing architectural violations in the Custom Mault Panel. Each notification includes:

Copy AI Prompt: Context-rich prompts optimized for any AI coding assistant
Dismiss - Reload: Clear alerts as necessary

17 detectors catch misplaced files, identify common security vulnerabilities, naming violations, deprecated patterns, config drift, and more.

Mault Pro ($99 activation + $7.99/month) includes all Core features plus automated governance, early access to updates, and Production Readiness Kit. Details below.

Mault Pro ($99 Activation + $7.99/month)

Mault Pro includes all Core features and is for developers who are serious about shipping production-ready software. Pay $99 to activate Pro, then $7.99/month for continued access to automated governance, early updates, and Production Readiness Kit.

What Pro Unlocks

Feature	What It Does
Production Readiness Kit	9-step journey from "runs locally" to production-ready
Automated Governance	Terminal-based auto-fix, not manual prompt copying
Governance Gate CI	GitHub Actions workflow for automated governance enforcement
Semi-Autonomous Workflow	Guided 5-step multi-agent flow with completion chimes and verification
Early Access	Get new detectors and features before Core users
14 Philosophy Guides	Battle-tested specs: Rising Tide, Iron Dome, TDD, Ratchet Strategy, etc.

Note: All 17 architectural detectors + basic runtime hooks are FREE forever in Core. Pro adds advanced runtime hooks, the Production Readiness Kit, Governance Gate CI, and Semi-Autonomous Workflow.

Runtime Hooks: Core vs Pro

Mault sets up runtime hooks for Claude Code that enforce development discipline at the AI agent level. Core users get basic enforcement via bash one-liners; Pro users get full-stack governance via Node.js scripts with layer awareness, transcript scanning, and session context injection.

Core Hooks (Free) — 3 bash one-liners in .claude/settings.json:

Hook	Type	What It Enforces
Test-First Gate	PreToolUse	Blocks file edits if no corresponding test file exists (simple glob matching)
Monolith Gate	PostToolUse	Blocks files exceeding 600 lines
Test Suite Gate	Stop	Runs `npm test` or `pytest` when the session ends

Pro Hooks (Advanced) — 5 Node.js entry points + shared library in .claude/hooks/:

Hook	Type	What It Enforces
Layer-Aware Test Gate	PreToolUse	Routes source files to the correct testing pyramid layer (pure-core, adapter-verification, behavioral, gold-standard, event-flow). Blocks if the correct test type is missing — not just any test.
Full SRP Monolith Gate	PostToolUse	Impl files: warn >300 / fail >600 LOC. Test files: warn >400 / fail >600 LOC. Functions >75 LOC blocked. Files >20KB blocked. Supports `.srp-exemptions.json` with expiration dates.
Hard-Coded Value Gate	PostToolUse	Scans for hard-coded semver versions, URLs, absolute paths, IP addresses, and port numbers. Escape hatch: `HARDCODE_OK: reason` inline comment.
Transcript-Aware Stop Gate	Stop	Parses the Claude Code JSONL transcript, extracts all source files modified during the session, and verifies each has a test in the correct pyramid layer.
Session Context Injection	SessionStart	Injects the full testing pyramid convention table into Claude's context — source-to-layer mapping, layer rules, excluded paths, and pattern references.

Why the difference? Core hooks use simple pattern matching (*.test.*) and line counting — effective for basic TDD enforcement. Pro hooks understand your project's testing architecture: adapters need adapter-verification tests, detectors need behavioral tests, commands need gold-standard tests. Pro also catches hard-coded values and scans the full session transcript to ensure nothing slips through.

For agents without Claude Code hooks (Cursor, Copilot, Windsurf, ChatGPT): The Monolith Detection (#16) and Missing Test Detection (#17) detectors provide equivalent enforcement through the Problems Panel. These detectors ensure that the testing rules and policies Mault helps you write (Steps 5 and 9) are enforced regardless of which AI coding assistant you use.

Getting Started with Pro

Step 1: Purchase Pro via the extension or mault.ai/billing

Step 2: Copy Setup Prompt into your AI coding assistant (Claude Code, Cursor, Copilot, ChatGPT):

Run command "Mault: Open Production Readiness Kit (Pro)" and set up my project.

1. Read the Production Readiness Kit that opens
2. Follow the 9-step journey to make my project production-ready
3. Tell me to check the Problems Panel when each step is complete

Step 3: Watch Progress in the Problems Panel (Ctrl+Shift+M / Cmd+Shift+M):

mault-pro-setup (9)
  ⚠ Step 1/9: Git Repository — Not initialized
  ⚠ Step 2/9: Environment Setup — .env.example missing
  ⚠ Step 3/9: Containerization — Dockerfile missing
  ...

Step 4: Use Quick Fix Actions on each step:

Click the lightbulb (💡) or press Ctrl+. / Cmd+. on any step
🤖 Copy AI Prompt for Step N — Copies a context-rich prompt for your AI coder
⏭️ Ignore Step N — Hide completed or skipped steps from Problems Panel

Step 7: Mault Enforcement — The AI configures your mault.yaml rulebook, verifies detectors fire with canary files, and sets up Pro features. Reload VS Code when prompted.

Freemium: Steps 1-3 and Step 9 are available to Core (free) users. Steps 4-8 require Pro.

Done! Problems Panel clears as steps complete. Your project is now production-ready with CI/CD, TDD, pre-commit hooks, and governance enforcement.

The 9-Step Journey

Step	Category	What It Creates
1	Infrastructure	Git repository, .gitignore, branch conventions
2	Infrastructure	.env.example, secrets management
3	Infrastructure	Dockerfile, docker-compose.yml
4	Infrastructure	CI/CD pipeline (GitHub Actions)
5	Testing	TDD framework (Jest/pytest/go test/JUnit)
6	Hooks	Pre-commit hooks (up to 9 layers)
7	Enforcement	Mault polyglot detectors + drift detection
8	Governance	AI-generated governance scripts
9	Testing Rules	AI coder testing rules (.cursorrules, copilot-instructions)

For deep-dive documentation, see Pro: Production Readiness Kit below.

Commands

Access via Command Palette (Ctrl+Shift+P / Cmd+Shift+P).

Setup & Configuration

Command	Description
`Mault: Initialize`	Initialize Mault in the workspace
`Mault: Open AI Coder Guide`	Open the setup guide for AI assistants
`Mault: Audit Configuration`	Check mault.yaml validity
`Mault: Set Detection Level`	Choose Gentle (1), Balanced (2), or Full (3)

Mault Panel Actions

Primary workflow: Use the Mault Panel sidebar for one-click Universal Prompts

Command	Description
`Mault: Copy Universal Prompt`	Copy AI-ready prompt for selected category
`Mault: Dismiss Finding`	Remove finding from Mault Panel
`Mault: Refresh Panel`	Re-run all detectors and refresh findings

Manual Analysis Triggers

Command	Description
`Mault: Analyze dead-end directories`	Find unreferenced folders
`Mault: Find Scattered Utils`	Locate misplaced utility files
`Mault: Analyze naming conventions`	Check naming violations
`Mault: Analyze file proliferation`	Find duplicate/versioned files
`Mault: Analyze flat architecture`	Check for overcrowded directories

Advanced Analysis Commands

Command	Description
`Mault: Generate Architecture Diagram`	Visualize dependency graph
`Mault: Analyze dependency health`	Check for vulnerable packages
`Mault: Analyze structural compliance`	AST-based pattern analysis

Pro-Only Commands

Command	Description
`Mault: Open Production Readiness Kit (Pro)`	Open bundled production-ready specs
`Mault: Create Test File (Testing Pyramid)`	Create test file with layer routing
`Mault: Reset Production Readiness Steps 1-3`	Reset local infrastructure steps
`Mault: Reset Production Readiness Steps 4-8 (Admin)`	Reset Pro steps (admin only)
`Mault: Show Funnel Analytics (Admin)`	Stakeholder analytics dashboard

17 Architectural Detectors

#	Detector	What It Catches	Language Support
1	Directory Reinforcement	Files placed in wrong folders	Polyglot
2	Legacy Path Prevention	Deprecated libraries, patterns, or APIs	Polyglot
3	Convention Reinforcement	Naming convention violations (camelCase vs snake_case)	Polyglot
4	Environment Reinforcement	OS-specific paths or commands that break cross-platform	Polyglot
5	Temporary Files	Clutter from .log, .tmp, .cache files	Polyglot
6	Flat Architecture	Too many files in source root without structure	Polyglot
7	Configuration Chaos	Missing critical configs (.gitignore, tsconfig, Dockerfile)	Polyglot
8	File Proliferation	Versioned duplicates (_v1, _backup, _old files)	Polyglot
9	Naming Chaos	Inconsistent file naming across the project	Polyglot
10	Overcrowded Folders	Folders with too many mixed file types	Polyglot
11	Scattered Utils	Utility functions not centralized in shared location	JS/TS (import analysis)
12	Dead-End Directories	Unused folders with unreferenced code	JS/TS (import analysis)
13	Dependency Health	Outdated or vulnerable packages	JS/TS (npm audit)
14	Application Flows	High-impact file changes + architecture diagram visualization	JS/TS (import analysis)
15	Structural Governance	AST-based pattern enforcement (exports, signatures, imports)	JS/TS, Python (AST)
16	Monolith Detection	Files/functions exceeding LOC thresholds (rising-tide model)	TS/JS, Python, Go, Rust, Java, Kotlin, C#
17	Missing Test Detection	Source files without corresponding test files in correct pyramid layer	JS/TS, Python

Language Support Key:

Polyglot: Works with any language via file/folder pattern matching
JS/TS: Requires JavaScript/TypeScript for import/dependency analysis

Requirements

VS Code 1.104+
A workspace containing docs/mault.yaml (version: 1)
Trusted workspace for full functionality

Pricing

Tier	Price	What's Included
Mault Core	FREE forever	17 architectural detectors, AI prompts, quick fixes
Mault Pro	$99 + $7.99/mo	All Core + automated governance, early access, Production Readiness Kit

Pro Pricing Model:

$99 one-time activation unlocks Pro features
30-day grace period included
$7.99/month subscription required after grace period
If subscription lapses, you return to Core FREE

Manage billing at mault.ai/billing

Release Notes

See CHANGELOG.md for detailed release notes.

1. Directory Reinforcement

Problem: Files are placed in the wrong folders, violating project structure conventions.

Example:

❌ src/utils/UserService.ts      # Wrong: Service in utils/
✅ src/services/UserService.ts   # Correct: Service in services/

Technical Flow

┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ File watcher detects file save/change
    │
    ├─▶ DirectoryDetector analyzes file path
    │   - Reads `docs/mault.yaml` for directory rules
    │   - Checks file name against expected directories
    │   - Example rule: "*Service.ts" → "src/services/"
    │
    └─▶ Creates DirectoryViolation finding

┌─────────────────────────────────────────────────────────────┐
│ 2. MAULT PANEL NOTIFICATION                                 │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Finding routed to Mault Panel (sidebar)
    │   - Category: "Directory Reinforcement"
    │   - Message: "File should be in src/services/ based on naming"
    │   - Impact annotation: "🔴 23 direct, 41 transitive dependents"
    │
    ├─▶ Panel groups findings by category with counts
    │   - e.g., "Scaffolding (7)", "File Proliferation (6)"
    │
    └─▶ One-click "Copy Universal Prompt" per category

┌─────────────────────────────────────────────────────────────┐
│ 3. USER ACTIONS (in Mault Panel)                            │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User clicks category in Mault Panel
    │
    └─▶ Actions available:
        ├─ 📋 Copy Universal Prompt — AI-ready prompt with triage guidance
        ├─ 🔄 Dismiss - Reload — Clear alerts as needed
        └─ 🔗 Click finding to jump to file location

┌─────────────────────────────────────────────────────────────┐
│ 4. RESOLUTION (Option A: Quick Fix)                         │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User selects "Move to src/services/"
    │
    ├─▶ Extension executes file move
    │   - Creates target directory if needed
    │   - Moves file to correct location
    │   - Updates imports in other files (future)
    │
    └─▶ Mault Panel refreshes, category count decreases

┌─────────────────────────────────────────────────────────────┐
│ 5. RESOLUTION (Option B: Universal Prompt)                  │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User clicks "Copy Universal Prompt" in Mault Panel
    │
    ├─▶ Extension generates context-rich prompt:
    │   - Triage question: "Are these files legitimately misplaced?"
    │   - Full issue list (not truncated)
    │   - Decision tree with fix actions
    │   - Impact annotations for high-dependency files
    │
    ├─▶ Prompt copied to clipboard
    │
    ├─▶ User pastes into Cursor/Copilot/Claude/ChatGPT
    │
    └─▶ AI has full context to execute fix

---

## 2. Legacy Path Prevention

**Problem:** AI Coder imports deprecated libraries or use outdated patterns.

**Example:**
```typescript
❌ import { utils } from '../../../legacy/old-utils';
✅ import { utils } from '@/utils/modern-utils';

Technical Flow

┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ File watcher detects file save/change
    │
    ├─▶ LegacyPatternDetector scans file content
    │   - Reads `docs/mault.yaml` for deprecated patterns
    │   - Uses regex to find matches
    │   - Example: /from ['"].*\/legacy\/.*/
    │
    └─▶ Creates LegacyPatternViolation finding

┌─────────────────────────────────────────────────────────────┐
│ 2. MAULT PANEL NOTIFICATION                                 │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Finding routed to Mault Panel (sidebar)
    │   - Category: "Legacy Patterns"
    │   - Message: "Deprecated: Use @/utils/modern-utils instead"
    │   - Recommended replacement shown
    │
    └─▶ Panel groups all legacy pattern findings together

┌─────────────────────────────────────────────────────────────┐
│ 3. USER ACTIONS (in Mault Panel)                            │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User clicks "Legacy Patterns" category in Mault Panel
    │
    └─▶ Actions available:
        ├─ 📋 Copy Universal Prompt — Full migration guidance
        ├─ 🔗 Click finding to jump to import line
        └─ 🔄 Dismiss - Reload

┌─────────────────────────────────────────────────────────────┐
│ 4. RESOLUTION (Option A: Quick Fix)                         │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User selects "Replace Deprecated Pattern"
    │
    ├─▶ Extension performs text replacement
    │   - Old: import { utils } from '../../../legacy/old-utils';
    │   - New: import { utils } from '@/utils/modern-utils';
    │
    └─▶ Mault Panel refreshes, category count decreases

┌─────────────────────────────────────────────────────────────┐
│ 5. RESOLUTION (Option B: Universal Prompt)                  │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User clicks "Copy Universal Prompt" in Mault Panel
    │
    ├─▶ Extension generates context-rich prompt:
    │   - Triage: "Is this pattern genuinely deprecated?"
    │   - Decision tree: validate rule → apply fix
    │   - All affected imports listed
    │
    ├─▶ Prompt copied to clipboard
    │
    └─▶ User pastes into AI assistant

---

## 3. Convention Reinforcement

**Problem:** AI Coders are inconsistent with naming conventions (camelCase vs snake_case, etc.)

**Example:**
```typescript
❌ const user_name = "John";      // snake_case in TypeScript
✅ const userName = "John";       // camelCase (correct)

Technical Flow

┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                 │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ File watcher detects file save/change
    │
    ├─▶ NamingConventionDetector analyzes identifiers
    │   - Reads `docs/mault.yaml` for naming rules
    │   - Checks variables, functions, classes
    │   - Example rule: TypeScript variables → camelCase
    │
    └─▶ Creates NamingViolation finding

┌─────────────────────────────────────────────────────────────┐
│ 2. MAULT PANEL NOTIFICATION                                  │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Finding routed to Mault Panel (sidebar)
    │   - Category: "Naming Conventions"
    │   - Message: "Use camelCase for variables (user_name → userName)"
    │
    └─▶ Panel groups all naming violations together

┌─────────────────────────────────────────────────────────────┐
│ 3. USER ACTIONS (in Mault Panel)                             │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User clicks "Naming Conventions" category in Mault Panel
    │
    └─▶ Actions available:
        ├─ 📋 Copy Universal Prompt — Includes triage: "Does rule match language conventions?"
        ├─ 🔗 Click finding to jump to variable
        └─ 🔄 Dismiss - Reload

┌─────────────────────────────────────────────────────────────┐
│ 4. RESOLUTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User selects "Rename to userName"
    │
    ├─▶ Extension performs rename refactoring
    │   - Uses VS Code's rename API
    │   - Updates all references
    │
    └─▶ Mault Panel refreshes, category count decreases

---

## 4. Environment Reinforcement

**Problem:** Code uses OS-specific paths or commands that break on other platforms.

**Example:**
```typescript
❌ const path = "C:\\Users\\John\\file.txt";  // Windows-only
✅ const path = path.join(os.homedir(), "file.txt");  // Cross-platform

Technical Flow

┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ EnvironmentDetector scans for OS-specific code
    │   - Hard-coded Windows paths (C:\, D:\)
    │   - Hard-coded Unix paths (/usr/local/)
    │   - OS-specific commands (cmd.exe, bash)
    │
    └─▶ Creates EnvironmentViolation finding

┌─────────────────────────────────────────────────────────────┐
│ 2. MAULT PANEL NOTIFICATION                                 │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Finding routed to Mault Panel (sidebar)
    │   - Category: "Environment Issues"
    │   - Message: "Windows-specific path. Use path.join() for cross-platform."
    │
    └─▶ Panel groups all environment findings together

┌─────────────────────────────────────────────────────────────┐
│ 3. RESOLUTION (in Mault Panel)                              │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Copy Universal Prompt — Includes cross-platform fix guidance
    │
    └─▶ Quick Fix: Replace with path.join()

---

## 5. Application Flow Analysis (UC13)

> **Language Support:** JS/TS only (import analysis)

**Problem:** Changes to high-impact files break unrelated workflows due to hidden dependencies.

**Example:**
```typescript
// User opens AuthService.ts
// Warning: This file affects CheckoutFlow, AdminPanel, ReportGenerator
❌ Modify without knowing 47 files depend on it
✅ See impact analysis before making changes
```

### Technical Flow

┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION (on activation + file open)                    │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ DependencyGraphBuilder analyzes imports on activation
    │   - Scans workspace for TS/JS files (max 1000)
    │   - Builds dependentsMap and importsMap
    │   - Computes transitive dependencies via BFS
    │
    ├─▶ FlowMapper reads docs/mault.yaml
    │   - Maps files to business flows (auth, checkout, etc.)
    │   - Identifies critical flows for severity boosting
    │
    └─▶ On file open: Creates ImpactAnalysis finding

┌─────────────────────────────────────────────────────────────┐
│ 2. MAULT PANEL NOTIFICATION                                 │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Finding routed to Mault Panel (sidebar)
    │   - Category: "Application Flow"
    │   - Message: "[IMPACT] High-impact file: 5 direct,
    │              15 transitive | In flows: auth, payment"
    │   - 🔴 High-impact annotation shown
    │
    └─▶ Impact enrichment adds severity multiplier

┌─────────────────────────────────────────────────────────────┐
│ 3. USER ACTIONS (in Mault Panel)                            │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User clicks "Application Flow" category in Mault Panel
    │
    └─▶ Actions available:
        ├─ 📋 Copy Universal Prompt — Full impact context
        ├─ Show Impact Summary
        └─ 🔗 Click finding to jump to file

┌─────────────────────────────────────────────────────────────┐
│ 4. RESOLUTION                                               │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Copy Universal Prompt includes:
    │   - Dependency map (direct + transitive)
    │   - Business flows affected
    │   - Triage guidance for high-impact files
    │
    └─▶ AI Prompt: "Analyze high-impact file with 47 dependents
         across 3 business flows before refactoring"

---

## 6. Cleaning Temporary Files

**Problem:** `.log`, `.tmp`, `.cache` files clutter the workspace.

**Solution:** Detect and offer to delete temporary files.

### Technical Flow

```
┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ TempFileDetector scans workspace
    │   - Finds files matching temp patterns
    │   - Example: *.log, *.tmp, *.cache, node_modules/.cache
    │
    └─▶ Creates TempFileViolation findings

┌─────────────────────────────────────────────────────────────┐
│ 2. MAULT PANEL NOTIFICATION                                 │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Finding routed to Mault Panel (sidebar)
    │   - Category: "Temporary Files"
    │   - Shows count: "15 temp files found"
    │
    └─▶ Copy Universal Prompt for batch cleanup

┌─────────────────────────────────────────────────────────────┐
│ 3. RESOLUTION (in Mault Panel)                              │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User clicks "Copy Universal Prompt"
    │
    ├─▶ AI prompt includes:
    │   - Full list of temp files
    │   - Triage: "Are these safe to delete?"
    │   - Recommended .gitignore additions
    │
    └─▶ Files deleted, .gitignore updated
```

---

## 7. Fixing Disorganized Structures

**Problem:** Flat directory structure with 100+ files in one folder.

**Solution:** Detect overcrowded folders and suggest reorganization.

### Technical Flow

```
┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ FlatArchitectureDetector counts files per directory
    │   - Threshold: 20+ files = overcrowded
    │   - Analyzes file types and patterns
    │
    └─▶ Creates FlatArchitectureViolation

┌─────────────────────────────────────────────────────────────┐
│ 2. MAULT PANEL NOTIFICATION                                 │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Finding routed to Mault Panel (sidebar)
    │   - Category: "Flat Architecture"
    │   - Message: "src/ has 87 files. Consider organizing into subdirectories."
    │
    └─▶ Impact annotation shows dependency counts

┌─────────────────────────────────────────────────────────────┐
│ 3. RESOLUTION (in Mault Panel)                              │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Copy Universal Prompt includes:
    │   - Decision tree for reorganization
    │   - Triage: "Is complexity justified?"
    │   - Step-by-step fix actions
    │
    └─▶ User applies AI-generated reorganization plan

---

## 8. Adding Missing Configs

**Problem:** Project missing `.editorconfig`, `.prettierrc`, etc.

**Solution:** Detect missing config files and offer to scaffold them.

### Technical Flow

```
┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ ConfigDetector checks for required files
    │   - .editorconfig
    │   - .prettierrc
    │   - .eslintrc
    │   - tsconfig.json
    │
    └─▶ Creates MissingConfigViolation

┌─────────────────────────────────────────────────────────────┐
│ 2. MAULT PANEL NOTIFICATION                                 │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Finding routed to Mault Panel (sidebar)
    │   - Category: "Config Chaos"
    │   - Shows missing configs with tier classification
    │   - Hard errors vs project-dependent flags
    │
    └─▶ Panel groups findings by severity

┌─────────────────────────────────────────────────────────────┐
│ 3. RESOLUTION (in Mault Panel)                              │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Copy Universal Prompt includes:
    │   - Tier-aware guidance (always fix vs depends)
    │   - Triage: "Is this config required for your project?"
    │   - Sensible defaults for scaffolding
    │
    └─▶ AI scaffolds config files with project-appropriate settings
```

---

## 9. Detecting File Proliferation

**Problem:** Versioned duplicates and backup copies clutter the workspace (`_v1`, `_backup`, `_old`, `_copy` files).

**Solution:** Detect versioned duplicate files and suggest consolidation.

### Technical Flow

```
┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ FileProliferationDetector scans workspace
    │   - Finds files with version suffixes (_v1, _v2, _backup, _old, _copy)
    │   - Identifies stale duplicates that should be removed
    │
    └─▶ Creates FileProliferationViolation

┌─────────────────────────────────────────────────────────────┐
│ 2. MAULT PANEL NOTIFICATION                                 │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Finding routed to Mault Panel (sidebar)
    │   - Category: "File Proliferation"
    │   - Message: "Versioned duplicate: report_v1.ts — consolidate or remove"
    │
    └─▶ Panel groups all proliferation findings together

┌─────────────────────────────────────────────────────────────┐
│ 3. RESOLUTION (in Mault Panel)                              │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Copy Universal Prompt includes:
    │   - All versioned duplicate locations
    │   - Recommended consolidation path
    │   - Guidance on which version to keep
    │
    └─▶ User applies AI-generated cleanup

---

## 10. Standardizing Naming

**Problem:** Inconsistent file naming (kebab-case vs camelCase vs snake_case).

**Solution:** Detect naming inconsistencies and suggest standardization.

### Technical Flow

```
┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ FileNamingDetector scans all files
    │   - Checks file name patterns
    │   - Example: UserService.ts vs user-service.ts
    │
    └─▶ Creates FileNamingViolation

┌─────────────────────────────────────────────────────────────┐
│ 2. MAULT PANEL NOTIFICATION                                 │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Finding routed to Mault Panel (sidebar)
    │   - Category: "Naming Conventions"
    │   - Message: "Use kebab-case for files (UserService.ts → user-service.ts)"
    │
    └─▶ Panel groups all naming issues together

┌─────────────────────────────────────────────────────────────┐
│ 3. RESOLUTION (in Mault Panel)                              │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Copy Universal Prompt includes:
    │   - Triage: "Does naming rule match project conventions?"
    │   - Batch rename guidance
    │   - Import update commands
    │
    └─▶ Quick Fix: Rename file to kebab-case
```

---

## 11. Organizing Overcrowded Folders

**Problem:** Single folder with 100+ files of different types.

**Solution:** Same as [#7](https://github.com/nootan-ai/mault-memory-layer/issues/7) (Fixing Disorganized Structures).

**Suggested Organization:**

```
Before:
src/
├── UserService.ts
├── ProductService.ts
├── OrderService.ts
├── UserController.ts
├── ProductController.ts
├── ... (95 more files)

After:
src/
├── services/
│   ├── UserService.ts
│   ├── ProductService.ts
│   └── OrderService.ts
├── controllers/
│   ├── UserController.ts
│   └── ProductController.ts
└── models/
    └── ...

---

## 12. Centralizing Shared Code

> **Language Support:** JS/TS only (import analysis for auto-update)

**Problem:** Utility functions scattered across project instead of in shared location.

**Solution:** Detect scattered utilities and suggest centralization.

### Technical Flow

```
┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ SharedCodeDetector finds utility-like files
    │   - Files with "helper", "util", "common" in name
    │   - Files outside utils/ or shared/ directories
    │
    └─▶ Creates ScatteredUtilityViolation

┌─────────────────────────────────────────────────────────────┐
│ 2. MAULT PANEL NOTIFICATION                                 │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Finding routed to Mault Panel (sidebar)
    │   - Category: "Scattered Utils"
    │   - Message: "Utility file should be in src/utils/"
    │
    └─▶ Panel groups all scattered utilities together

┌─────────────────────────────────────────────────────────────┐
│ 3. RESOLUTION (in Mault Panel)                              │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Copy Universal Prompt includes:
    │   - All scattered utility locations
    │   - Centralization path recommendation
    │   - Import update guidance
    │
    └─▶ Quick Fix: Move to src/utils/
```

---

## 13. Dependency Health [Core + Pro]

> **Language Support:** JS/TS only (npm/yarn/pnpm audit)

**Problem:** Security vulnerabilities in npm/yarn/pnpm dependencies go unnoticed until security audits or production incidents.

**Example:**
```typescript
// package.json has lodash@4.17.20
// Known vulnerability: GHSA-xxx-xxx (Prototype Pollution, High severity)
// Detection: "Vulnerable package: lodash@4.17.20 - GHSA-xxx-xxx (High)"
// Fix: npm audit fix or upgrade to 4.17.21
```

### Technical Flow

```
+---------------------------------------------------------+
| 1. DETECTION (on activation + manual trigger)           |
+---------------------------------------------------------+
    |
    +-> DependencyHealthDetector runs package manager audit
    |   - Detects package manager (npm/yarn/pnpm)
    |   - Executes audit command (npm audit --json)
    |   - Parses JSON output for vulnerabilities
    |
    +-> Maps audit results to findings
    |   - CVE/GHSA advisory identifiers
    |   - Severity mapping (critical, high, moderate, low)
    |   - Affected package and version
    |   - Remediation suggestion (fix version)
    |
    +-> Creates DependencyHealthFinding for each vulnerability

+---------------------------------------------------------+
| 2. MAULT PANEL NOTIFICATION                             |
+---------------------------------------------------------+
    |
    +-> Finding routed to Mault Panel (sidebar)
    |   - Category: "Dependency Health"
    |   - Severity: Error (critical/high) or Warning (moderate/low)
    |   - Message: "Vulnerable package: lodash@4.17.20 -
    |              GHSA-xxx-xxx (High severity)"
    |
    +-> Panel groups vulnerabilities by severity

+---------------------------------------------------------+
| 3. USER ACTIONS (in Mault Panel)                        |
+---------------------------------------------------------+
    |
    +-> User clicks "Dependency Health" category
    |
    +-> Actions available:
        +- Copy Universal Prompt — Full vulnerability context
        +- Run npm audit fix

+---------------------------------------------------------+
| 4. RESOLUTION                                           |
+---------------------------------------------------------+
    |
    +-> Quick Fix: Copy fix command to clipboard
    |   - "npm audit fix" or "npm update lodash@4.17.21"
    |
    +-> AI Prompt: "Analyze vulnerable dependency lodash@4.17.20
         with GHSA-xxx-xxx (High severity). Recommend upgrade
         path considering breaking changes."

---

## 14. Architecture Diagrams [Core + Pro]

> **Note:** Architecture Diagrams is the visualization layer for the Application Flows detector (#14). It is not counted as a separate detector.
>
> **Language Support:** JS/TS (import analysis); Polyglot for file-level diagrams

**Problem:** Understanding large codebases is difficult without visualization. Developers need to see how files relate before making architectural changes.

**Example:**
```typescript
// User runs "Mault: Generate Architecture Diagram"
// Output: Mermaid diagram showing dependency relationships
//
// graph TD
//     AuthService --> TokenManager
//     AuthService --> UserRepository
//     CheckoutController --> AuthService
//     CheckoutController --> PaymentService
```

### Technical Flow

```
+---------------------------------------------------------+
| 1. DETECTION (on activation + file open)                |
+---------------------------------------------------------+
    |
    +-> DependencyGraphBuilder analyzes imports on activation
    |   - Scans workspace for TS/JS files (max 1000)
    |   - Builds dependentsMap and importsMap
    |   - Computes transitive dependencies via BFS
    |
    +-> FlowMapper reads docs/mault.yaml
    |   - Maps files to business flows (auth, checkout, etc.)
    |   - Identifies critical flows for severity boosting
    |
    +-> Caches dependency graph for diagram generation

+---------------------------------------------------------+
| 2. MAULT PANEL NOTIFICATION                             |
+---------------------------------------------------------+
    |
    +-> Finding routed to Mault Panel (sidebar)
    |   - Category: "Application Flow"
    |   - Severity: High-impact annotation
    |   - Message: "[IMPACT] High-impact file: 5 direct,
    |              15 transitive | In flows: auth, payment"
    |
    +-> Command Palette: "Mault: Generate Architecture Diagram"

+---------------------------------------------------------+
| 3. USER ACTIONS                                         |
+---------------------------------------------------------+
    |
    +-> User runs "Mault: Generate Architecture Diagram"
    |
    +-> Options menu appears:
        +- Generate Full Dependency Graph
        +- Generate Flow-Specific Diagram (select flow)
        +- Generate File-Centric Diagram (current file)
        +- Copy Mermaid to Clipboard

+---------------------------------------------------------+
| 4. DIAGRAM GENERATION                                   |
+---------------------------------------------------------+
    |
    +-> MermaidDiagramGenerator processes dependency graph
    |   - Converts dependentsMap to Mermaid syntax
    |   - Applies flow coloring (auth=blue, payment=green)
    |   - Highlights high-impact nodes (thicker borders)
    |   - Limits nodes for readability (configurable max)
    |
    +-> Output options:
        +- Preview in VS Code webview panel
        +- Copy Mermaid code to clipboard
        +- Export as PNG/SVG (via Mermaid CLI)

+---------------------------------------------------------+
| 5. VISUALIZATION OUTPUT                                 |
+---------------------------------------------------------+
    |
    +-> Webview Panel displays interactive diagram
    |   - Click node to open file
    |   - Hover for dependency count tooltip
    |   - Zoom/pan controls
    |
    +-> Mermaid code example:
        graph TD
            subgraph Authentication
                AuthService[AuthService.ts]
                TokenManager[TokenManager.ts]
                UserRepository[UserRepository.ts]
            end
            subgraph Checkout
                CheckoutController[CheckoutController.ts]
                PaymentService[PaymentService.ts]
            end
            AuthService --> TokenManager
            AuthService --> UserRepository
            CheckoutController --> AuthService
            CheckoutController --> PaymentService
            style AuthService fill:#ff6b6b,stroke:#333,stroke-width:3px

---

## 15. Structural Governance [Core]

> **Language Support:** JS/TS (AST analysis), Python (AST analysis)

**Problem:** Teams establish architectural patterns (all services must export a specific interface, handlers must follow a signature) but have no way to enforce them. AI coders generate code that ignores established patterns.

**Example:**
```typescript
// governance.rules in mault.yaml requires:
// - All services export a default class
// - All handlers have handle(request, response) signature
// - No console.log in production code

// StructuralComplianceDetector finds:
❌ src/services/UserService.ts - Missing default export
❌ src/handlers/AuthHandler.ts - handle() missing 'response' param
❌ src/utils/logger.ts - Forbidden pattern: console.log
✅ src/services/PaymentService.ts - Compliant
```

### Technical Flow

```
+---------------------------------------------------------+
| 1. DETECTION (on file save + manual trigger)            |
+---------------------------------------------------------+
    |
    +-> StructuralComplianceDetector loads governance rules
    |   - Reads governance.rules from docs/mault.yaml
    |   - Validates rule configuration via configLoader
    |   - Groups rules by target file patterns
    |
    +-> For each file matching rule targets:
    |
    +-> SYNC: Structural Assertions (Core)
    |   |
    |   +-> export_exists: Check named exports match pattern
    |   |   - Uses TypeScript AST to find export declarations
    |   |   - Validates export name/kind against assertion
    |   |
    |   +-> function_signature: Validate function params/returns
    |   |   - Parses function declarations via AST
    |   |   - Compares params against requiredParams
    |   |
    |   +-> import_exists: Check required imports present
    |   |   - Scans import declarations
    |   |   - Validates module specifiers
    |   |
    |   +-> ast_skeleton: Match against structural templates
    |   |   - Uses skeletonMatcher for pattern matching
    |   |   - Compares AST structure against template
    |   |
    |   +-> forbidden_pattern: Detect banned code patterns
    |       - Applies regex patterns to file content
    |       - Flags matches with line/column positions
    |
    +-> ASYNC: Semantic Similarity (Pro-only)
        |
        +-> semantic_similarity: Compare against gold standard
            - Normalizes code (strips comments/whitespace)
            - Generates embeddings via OpenAI API
            - Queries Pinecone vector database
            - Returns similarity score vs threshold

+---------------------------------------------------------+
| 2. MAULT PANEL NOTIFICATION                             |
+---------------------------------------------------------+
    |
    +-> Finding routed to Mault Panel (sidebar)
    |   - Category: "Structural Governance"
    |   - Severity: Error (structural) or Warning (semantic)
    |   - Message varies by assertion type:
    |     • "Missing required export: default class"
    |     • "Function 'handle' missing parameter: response"
    |     • "Forbidden pattern detected: console.log"
    |     • "Similarity score 0.45 below threshold 0.70"
    |
    +-> Panel groups violations by file

+---------------------------------------------------------+
| 3. USER ACTIONS (in Mault Panel)                        |
+---------------------------------------------------------+
    |
    +-> User clicks "Structural Governance" category
    |
    +-> Actions available:
        +- Copy Universal Prompt — Full violation context
        +- Show Violation Details
        +- View Gold Standard Example (semantic only)

+---------------------------------------------------------+
| 4. RESOLUTION                                           |
+---------------------------------------------------------+
    |
    +-> AI Prompt generated with full context:
    |   - Rule ID and assertion type
    |   - Expected pattern/signature/structure
    |   - Current code snippet
    |   - Similar implementations (for semantic)
    |
    +-> User applies fix manually or via AI assistant
    |
    +-> Re-scan on save clears resolved violations

---

## 16. Monolith Detection [Core]

> **Language Support:** TS/JS, Python, Go, Rust, Java, Kotlin, C# (file-level LOC); C-style languages (function-level LOC)

**Problem:** Files and functions grow unbounded, especially when AI coders generate code without size awareness. A 2,000-line service file becomes impossible to review, test, or refactor.

**Example:**
```
src/services/UserService.ts — 1,247 lines (threshold: 1,000)
  ⚠ Function processOrder() — 187 lines (threshold: 100)
  ⚠ Function validateCart() — 142 lines (threshold: 100)
```

### Rising-Tide Model

The monolith detector uses a **persistent rising-tide model** — existing file sizes are grandfathered, but growth is blocked:

- Findings persist across VS Code restarts (stored in workspaceState)
- A finding only disappears when the file is fixed (LOC reduced) or deleted
- New violations are caught immediately on file save
- Stale entries are pruned automatically when files are deleted

### Thresholds

| Target | Warn | Error |
|--------|------|-------|
| Source file LOC | 750 | 1,000 |
| Test file LOC | 500 | 700 |
| Function LOC | — | 100 |

Thresholds are configurable via `docs/mault.yaml` under `monolithDetection`.

### Technical Flow

```
+---------------------------------------------------------+
| 1. DETECTION (on file save + activation + manual)       |
+---------------------------------------------------------+
    |
    +-> MonolithDetector analyzes file content
    |   - Counts non-blank lines (CRLF-aware)
    |   - Classifies test vs source files
    |   - Detects function boundaries via brace-counting
    |   - Checks against configurable thresholds
    |
    +-> Creates MonolithFinding for each violation
    |   - file-loc: file exceeds LOC threshold
    |   - function-loc: function exceeds LOC threshold
    |
    +-> Findings persist in rising-tide cumulative map

+---------------------------------------------------------+
| 2. MAULT PANEL NOTIFICATION                             |
+---------------------------------------------------------+
    |
    +-> Finding routed to Problems Panel
    |   - Source: "mault-monolith"
    |   - Includes dependency context (direct/transitive)
    |   - AI-actionable relatedInformation
    |
    +-> Copy Universal Prompt for refactoring guidance

+---------------------------------------------------------+
| 3. RESOLUTION                                           |
+---------------------------------------------------------+
    |
    +-> User or AI coder splits file/function
    |
    +-> Re-scan on save clears resolved violations
    |
    +-> Rising-tide: quality can only improve
```

---

## 17. Missing Test Detection [Core]

> **Language Support:** JS/TS, Python

**Problem:** AI coding assistants like Cursor, Copilot, Windsurf, and ChatGPT do not support runtime hooks. When Mault helps users set up testing rules (Steps 5 and 9), those rules exist as documentation — policy, not physics. Without enforcement, AI coders silently skip writing tests for new source files.

The Missing Test Detector closes this gap. It provides a **detection layer** that catches violations of the testing policies Mault helps users establish, ensuring that even agents without runtime hooks are held accountable through the Problems Panel and Mault Panel alerts.

> **For Claude Code users**: Claude Code supports runtime hooks (PreToolUse, Stop), so Mault can enforce TDD at the point of code generation. The Missing Test Detector provides a second safety net and catches anything the hooks miss.
>
> **For all other AI coders**: This detector is the primary enforcement mechanism. It surfaces missing tests as errors in the Problems Panel, where AI coders can see and act on them.

### What It Detects

The detector runs three enforcement phases:

| Phase | What It Catches | Rule |
|-------|-----------------|------|
| **1. Missing Tests** | Source files without a corresponding test file in the correct testing pyramid layer | Layer-aware path resolution |
| **2. Layer Compliance** | Test files that violate layer rules (e.g., unit tests importing `vscode` or mocking I/O) | Architectural boundary enforcement |
| **3. Mock Tax** | Unit tests where test LOC / source LOC > 2.0x | Rising Tide 2x rule |

### Testing Pyramid Layer Resolution

The detector maps each source file to its expected test layer based on its role in the architecture:

| Source File Pattern | Expected Test Layer | Test Location |
|---------------------|---------------------|---------------|
| `adapters/*.ts` | Adapter Verification | `tests/integration/adapters/` |
| `**/detectors/*Detector.ts` | Behavioral | `tests/behavioral/` |
| `commands/*.ts` | Gold Standard | `tests/integration/commands/` |
| `**/registries/**`, `**/triggers/**` | Event Flow | `tests/integration/event-flows/` |
| Other source files | Pure Core (unit) | `tests/unit/` |
| Python `repositories/` | Adapter Verification | `tests/` |
| Python `routes/` | Gold Standard | `tests/` |

Files in `ports/`, `constants/`, `types/`, and `.d.ts` are excluded (no test required).

### CodeLens Integration

When a source file is missing its test, a **CodeLens indicator** appears at line 1:

```
Test needed: tests/unit/services/UserService.test.ts (pure-core)
[Create Test]
```

Clicking **[Create Test]** scaffolds the test file at the correct path with a layer-appropriate template — different boilerplate for pure-core, gold-standard, behavioral, adapter-verification, and event-flow tests.

### Technical Flow

```
+---------------------------------------------------------+
| 1. DETECTION (on activation + file save)                |
+---------------------------------------------------------+
    |
    +-> TestPyramidEnforcerService scans workspace
    |   - Resolves each source file to expected test layer
    |   - Checks filesystem for corresponding test file
    |   - Uses hexagonal architecture (Port/Adapter pattern)
    |
    +-> Phase 1: Missing test files identified
    |
    +-> Phase 2: TestLayerComplianceService checks existing
    |   tests for layer rule violations
    |   - Unit tests must not import vscode
    |   - Unit tests must not jest.mock I/O modules
    |   - Integration tests must not use inline mock factories
    |
    +-> Phase 3: MockTaxEnforcerService calculates ratios
        - Test LOC / Source LOC > 2.0x = violation
        - Triggers Rising Tide rule: delete unit test,
          rewrite as integration test

+---------------------------------------------------------+
| 2. MAULT PANEL NOTIFICATION                             |
+---------------------------------------------------------+
    |
    +-> Findings routed to Problems Panel
    |   - Source: "mault-test-pyramid"
    |   - Category: "Missing Tests"
    |   - Severity: Warning (missing) or Error (compliance)
    |
    +-> CodeLens shows inline [Create Test] action
    |
    +-> Copy Universal Prompt for test generation

+---------------------------------------------------------+
| 3. RESOLUTION                                           |
+---------------------------------------------------------+
    |
    +-> Option A: Click [Create Test] CodeLens
    |   - Scaffolds test at correct pyramid layer
    |   - Pre-populates with layer-appropriate template
    |
    +-> Option B: Copy Universal Prompt
    |   - AI generates test with full context
    |   - Layer routing ensures correct test location
    |
    +-> Re-scan on save clears resolved violations
```

### Configuration

Configure via `docs/mault.yaml` under `testPyramid`:

```yaml
testPyramid:
  sourcePatterns:
    - "src/**/*.ts"
  excludePatterns:
    - "**/*.d.ts"
    - "**/types/**"
  testPatterns:
    - "tests/**/*.test.ts"
```

---

## Pro: Production Readiness Kit

> **Tier**: Pro-only ($99 activation + $7.99/month)

The Production Readiness Kit is a structured 9-step journey that takes your project from "runs locally" to "production-ready." It provides battle-tested philosophy guides that any AI coder can follow to set up production infrastructure.

> **Freemium Access**: Steps 1-3 (Git, Environment, Containerization) and Step 9 (AI Coder Testing Rules) are available to all Core users for free. Steps 4-8 require Pro.
>
> **AGENT-INSTRUCTIONS Format**: Steps 4-9 use the `YOU ARE THE AGENT` mission brief format with numbered CHECKs, ANTI-PATTERNS sections, and Ralph Loop verification.
>
> **Orchestrator Pattern (Steps 4-6)**: Steps 4, 5, and 6 use a compact orchestrator prompt (~6-8K) with 21 reference files written to `.mault/reference/stepN/`. Agents read the orchestrator first and pull reference files on demand, cutting prompt size by ~60% while increasing detail.

### Production Readiness Levels

| Level | Name | What It Means | Artifacts Created |
|-------|------|---------------|-------------------|
| 0 | Runs primarily locally | Core analysis executes on your machine; some features may make network requests | Just code |
| 1 | Reproducible | Someone else can run it | requirements.txt, .env.example |
| 2 | Portable | Runs in a container | Dockerfile, docker-compose.yml |
| 3 | Deployed | Runs in the cloud | CI/CD pipeline, cloud config |
| 4 | Reliable | Stays running | Health checks, logging, rollback |

**The Kit takes you from Level 0 → Level 4.**

### Philosophy Guides

These guides explain the **WHY** behind enforcement. AI coders read them and generate language-specific scripts.

#### Rising Tide (Mock Tax)

**The 2x Rule**: If a unit test is more than 2x the size of the source code, delete the unit test and write an integration test instead.

```
Test : Source Ratio    Interpretation        Action
──────────────────────────────────────────────────────────
< 1.0x                 Under-tested          Add more test cases
1.0x - 2.0x            Healthy               Maintain
2.0x - 3.0x            Mock Tax Warning      Consider integration test
> 3.0x                 Excessive             Delete, rewrite as integration
```

**Why**: Tests larger than their source code indicate tight coupling and excessive mocking. These tests are brittle and don't catch real bugs.

#### Iron Dome (Type Safety)

**The Ratchet Rule**: Type-safety holes (`any`, `type: ignore`, `eslint-disable`) can only decrease, never increase.

```
NEW holes BLOCKED           OLD holes GRANDFATHERED
─────────────────           ───────────────────────
Cannot add new `any`        Existing `any` allowed
Cannot add new `ignore`     Existing `ignore` allowed
Cannot disable more rules   Existing disables allowed

Result: Quality can only IMPROVE over time.
```

**Type Safety Holes by Language**:

| Language | Holes to Track |
|----------|----------------|
| TypeScript | `any`, `as any`, `@ts-ignore`, `@ts-expect-error`, `!` |
| Python | `type: ignore`, `Any`, `cast()`, `# noqa` |
| Go | `interface{}`, `any`, type assertions, `//nolint` |
| Java | Raw types, `@SuppressWarnings("unchecked")`, unchecked casts |

#### TDD Guide

**Red-Green-Refactor**:

```
1. RED     → Write failing test (captures intent)
2. GREEN   → Write minimum code to pass
3. REFACTOR → Clean up while tests protect
```

**The Pure Core Pattern**: Business logic with no I/O imports (easy to test). Adapters are thin wrappers for I/O (tested via integration tests).

#### Ratchet Strategy

**Baseline + Improvement**: Count current violations, set as baseline, block any increase.

```
Day 0:  Generate baseline → 127 type holes
Day 5:  Developer adds 2 → BLOCKED (129 > 127)
Day 10: Developer fixes 5 → New baseline: 122
Day 30: Overall: 127 → 98 (23% reduction)
```

### Pre-commit Layers (Language-Specific)

The Kit sets up pre-commit hooks with up to 9 layers of protection. These are **language-specific governance patterns** that AI generates for your stack—use TypeScript as the reference implementation and adapt for your language:

**TypeScript Reference (9 Layers)**:

| Layer | Name | Purpose |
|-------|------|---------|
| 1 | Compilation & Static Analysis | Catch type errors Jest might mask |
| 2 | Rising Tide (Mock Tax) | Block oversized unit tests (2x rule) |
| 3 | Test Impact Analysis (TIA) | Run only affected tests |
| 4 | Adversarial Mock Scan | Prevent mocking reality |
| 5 | Precision Coverage Ratchet | Enforce 80% on new files |
| 6 | Security Gate | npm audit for vulnerabilities |
| 7 | Integration Test Pairing | Buddy System enforcement |
| 8 | Type Safety Gate (any Ratchet) | Block new `any` usage |
| 9 | Dead Code Gate | Detect silent catches |

These patterns apply to any language—AI adapts them to your stack (pytest for Python, go test for Go, JUnit for Java, etc.).

### Polyglot Detectors (All Languages)

In addition to language-specific hooks, Mault provides **9 polyglot detectors** that work with ANY language. These enforce architectural rules regardless of your stack:

| UC | Detector | What It Blocks |
|----|----------|----------------|
| UC01 | Directory Reinforcement | Files in wrong directories |
| UC02 | Legacy Prevention | Files in deprecated paths |
| UC04 | Environment Reinforcement | Missing/malformed .env |
| UC06 | Temp File Cleanup | Temp files in commits |
| UC07 | Flat Architecture | Too many files in root |
| UC08 | Config Chaos | Config files misplaced |
| UC09 | File Proliferation | Duplicate files |
| UC11 | Overcrowded Folders | Too many files per folder |
| UC13 | Application Flows | High-impact file warnings |

These detectors are configured via Step 7 (Mault Enforcement) and work on Python, Go, Java, Rust, or any other language.

### New Detectors (#16, [#17](https://github.com/nootan-ai/mault-memory-layer/issues/17))

The following detectors are available FREE in Core:

| # | Detector | Language Support | What It Catches |
|---|----------|------------------|-----------------|
| 16 | Monolith Detection | TS/JS, Python, Go, Rust, Java, Kotlin, C# | Files/functions exceeding LOC thresholds (rising-tide) |
| 17 | Missing Test Detection | JS/TS, Python | Source files without tests in correct pyramid layer |

**AI Coder Guidance**: When setting up pre-commit hooks in Step 6:

1. **For JS/TS projects**: Add `npm audit --audit-level=high` as a pre-commit hook for UC16, and configure UC18 structural rules in `mault.yaml` under `governance.rules`

2. **For Python projects**: UC18 structural governance works via AST analysis. Configure rules in `mault.yaml`

3. **For other languages**: These detectors are roadmapped for Go (go mod audit), Java (OWASP Dependency-Check), and Rust (cargo audit). Until then, AI coders should add equivalent tooling to pre-commit manually

**Example pre-commit entry for UC16 (JS/TS)**:
```yaml
- repo: local
  hooks:
    - id: dependency-health
      name: Dependency Health (UC16)
      entry: npm audit --audit-level=high
      language: system
      pass_filenames: false
      stages: [commit]
```

### Files Created

After running the Production Readiness Kit, your project will have:

```
your-project/
├── .git/                           # Step 1
├── .gitignore                      # Step 1
├── .env.example                    # Step 2
├── Dockerfile                      # Step 3
├── docker-compose.yml              # Step 3
├── .dockerignore                   # Step 3
├── .github/
│   └── workflows/
│       └── ci.yml                  # Step 4
├── tests/
│   ├── unit/
│   │   └── governance/             # Step 8
│   └── integration/                # Step 5
├── .pre-commit-config.yaml         # Steps 6, 7, 8
├── scripts/
│   └── governance/                 # Step 8
│       ├── check-mock-tax.{js,py}
│       ├── check-type-safety.{js,py}
│       └── check-coverage-ratchet.{js,py}
├── .cursorrules                    # Step 9
├── .github/
│   └── copilot-instructions.md     # Step 9
├── .windsurfrules                  # Step 9
├── .augment-guidelines             # Step 9
└── .memory-layer/
    └── baselines/                  # Step 8
        ├── coverage.json
        ├── type-safety.json
        └── mock-tax.json
```

### Language Support

The Kit is **language-agnostic** by design. AI generates appropriate scripts for your stack.

**Fully tested:**

| Component | TypeScript/JS | Python |
|-----------|---------------|--------|
| Test Framework | Jest, Vitest | pytest |
| Type Checking | TypeScript | mypy |
| Linting | ESLint | ruff, flake8 |
| Pre-commit | pre-commit | pre-commit |

**Templates available (AI-generated, not yet fully tested):**

Go, Rust, Java, .NET, C++, Swift, Julia — Pro step content includes language-aware templates for these stacks. The AI adapts framework choices (go test, cargo test, JUnit 5, etc.) but these paths have not been end-to-end verified.

### Core Principle: Physics, Not Policy

> **"Agents obey Physics, not Policy"**

- **Policy**: Documentation, guidelines, best practices → AI ignores these
- **Physics**: Errors, blocked commits, failed CI → AI cannot bypass these

Every rule in the Production-Readiness Kit is enforced as **physics**:
- `warn` is policy (AI ignores)
- `error` is physics (AI cannot proceed)

### For Existing Projects

Same setup process, but AI detects what already exists:
- Has Git? → Skip Step 1
- Has Dockerfile? → Skip Step 3
- Has pre-commit? → Skip Step 6

**Rising Tide for Legacy**: Existing issues are grandfathered, new issues are blocked. Quality only improves.

---

## Governance Gate [Pro]

> **Tier**: Pro-only

The Governance Gate is a GitHub Actions workflow that enforces Mault governance rules in CI. It runs automatically on pull requests and blocks merges that introduce architectural violations.

**What It Does:**

- Detects your project's language stack (9 stacks supported: Node, Python, Go, Java, Rust, C#/.NET, C++, Swift, Julia)
- Runs Mault detectors as CI checks
- Blocks PRs that introduce new violations (rising-tide model)
- Integrates with branch protection rules

**Setup**: The Governance Gate is configured automatically during Step 8 (Governance Testing) of the Production Readiness Kit. An AGENT-INSTRUCTIONS prompt guides your AI coder through the setup.

---

## Semi-Autonomous Workflow [Pro]

> **Tier**: Pro-only
>
> **Prerequisites**: All 9 Production Readiness steps must be completed. This ensures your codebase has CI/CD, TDD, pre-commit hooks, and governance enforcement as a foundation before unlocking multi-agent productivity.
>
> **Requires Claude Code** with **bypass permissions** enabled. The seamless flow — click a role, settings are written, a Claude Code tab opens with the prompt auto-submitted — relies on Claude Code's hooks system (`PreToolUse`, `PostToolUse`, `Stop`, `SessionStart`) and `settings.local.json` permission model. Other AI assistants (Cursor, Copilot, Windsurf) can use Mault's detectors and setup prompts, but the Semi-Autonomous Workflow is only tested and supported with Claude Code. To enable bypass permissions: `Claude Code → /permissions → enable bypass`.

### Built for Developers Who Want Control

Fully autonomous AI workflows are fast — but they skip reviews, cut corners, and ship bugs you discover days later. The Semi-Autonomous Workflow gives you AI-powered speed with human-grade verification at every step.

**Who this is for:**

- **Vibe coders** who want AI to do the heavy lifting but don't fully trust fully autonomous flows
- **Teams** that require senior-level code reviews before anything hits main
- **Non-technical founders** who need guided testing and verification they can follow
- **Solo developers** who want to ship faster without sacrificing quality

### The 5-Step Guided Flow

Click a role in the Mault Panel. Settings are written, a Claude Code tab opens with the prompt auto-submitted. Zero friction.

| Step | Role | What It Does | Guardrails |
| ---- | ---- | ------------ | ---------- |
| 1 | **Planner** | Builds a plan WITH you — you approve every decision before anything is built | Read-only. Cannot create issues, write code, or modify files outside `.mault/` |
| 2 | **Orchestrator** | Creates atomic GitHub issues from your approved plan, each scoped and dependency-ordered | Can create issues and labels. Cannot write code or create PRs |
| 3 | **Worker** | Picks up issues one at a time, writes code, creates PRs with `mault-ready` labels | Full code access. **Cannot merge PRs** — that's the Review Agent's job |
| 4 | **Review Agent** | Merges PRs when CI passes. Checks for remaining tasks and `mault-needs-fix` PRs before advancing | Can merge PRs and manage issues. **Cannot create PRs** — that's the Worker's job |
| 5 | **Tester** | Verifies the work actually works. Runs tests, generates manual test plans, or suggests testing tools | **Read-only on source code.** Can only write test files and reports. Cannot install packages |

Each role writes `.claude/settings.local.json` with minimum-permission allowlists — agents can only do what their role allows. This is **physics, not policy**: the deny list is enforced by Claude Code itself, not by a prompt the agent can ignore.

### Completion Chime

Switch focus while agents work on 10-20 minute tasks. When a step completes, you'll hear a system beep and see a VS Code notification with:

- Which role just finished
- A brief summary of what was accomplished
- Which step to click next

**Example:** "Worker complete! 3 PRs created. Next: click Step 4: Review Agent"

The chime works on Windows (PowerShell), macOS (osascript), and Linux (paplay/spd-say). Disable it with `mault.sound.enabled` in VS Code settings.

### Verification-First: The Tester Role

The Tester (Step 5) is the quality gate that closes the loop. After the Review Agent merges PRs, the Tester verifies the work actually works:

- **Automated testing**: Runs `npm test`, E2E suites, linting, and type checking
- **Manual test plans**: For UI features or visual changes, generates a numbered step-by-step checklist in plain English that anyone can follow
- **Tool recommendations**: If test coverage gaps exist, suggests appropriate tools (Playwright, Cypress, etc.) and provides install commands — but cannot install them itself

**If tests pass**: Writes the final `workflow-complete.json` signal. Your workflow is done.

**If tests fail**: Routes you back to Worker(3) → Review(4) → Tester(5) until clean. For small one-line fixes, skip Planner and Orchestrator — go straight to Worker.

### The Full Flow

```
 Click "Step 1: Planner" in Mault Panel
  │
  ▼
 PLANNER ── builds plan with you ── writes .mault/plan.md
  │  🔔 Chime → "Next: Step 2 Orchestrator"
  ▼
 ORCHESTRATOR ── creates GitHub issues from plan
  │  🔔 Chime → "Next: Step 3 Worker"
  ▼
 WORKER ── picks up issues, writes code, creates PRs
  │  🔔 Chime → "Next: Step 4 Review Agent"
  ▼
 REVIEW AGENT ── merges PRs when CI is green
  │  🔔 Chime → checks for remaining work
  │
  ├── Open tasks remain? → "Go back to Step 3: Worker"
  │
  └── All done? → "Next: Step 5 Tester"
       │
       ▼
      TESTER ── runs tests, verifies everything works
       │
       ├── Tests pass? → 🎉 Workflow complete!
       └── Tests fail? → Loop: Worker → Review → Tester
```

### Multi-Agent Runtime Hooks (5)

These hooks layer on top of the Pro runtime hooks and enforce agent-level governance:

| Hook | Type | What It Enforces |
| ---- | ---- | ---------------- |
| **Agent Bootstrap** | SessionStart | Injects task boundaries, fix-first warnings (checks for `mault-needs-fix` PRs), and phase context |
| **Zone Boundary** | PreToolUse | Blocks file writes outside the agent's declared zone (from `.mault/current-task.json`) |
| **Budget Gate** | PostToolUse | Tracks cumulative `git diff` against file count and LOC budget. Warns at 80%, blocks at 100% |
| **Phase Gate** | PreToolUse | Enforces role separation: workers cannot merge PRs, reviewers cannot create PRs |
| **Receipt Gate** | Stop | Blocks session end unless the agent posts a structured receipt proving task completion |

> All multi-agent hooks **fail-open** — if the state files don't exist (not in agent mode), all operations are allowed. The hooks are safely composable and only activate during managed agent sessions.

---

## Data & Privacy Disclosure

Mault performs core governance and integrity analysis **locally** within VS Code. Certain features, such as dependency health checks, may perform network requests to retrieve external metadata.

**What connects to the internet:**

- **Authentication**: Email/OAuth for account creation
- **Payments**: Processed securely via Stripe (we never store card details)
- **Entitlement checks**: Subscription validation
- **Error reporting**: Crash diagnostics, no code content
- **Usage analytics**: Feature metrics, opt-out via `mault.usage.enabled` setting

**AI-powered features (optional, user-invoked only):**

- Code snippets may be processed to generate semantic embeddings
- Embeddings are stored for search functionality
- Raw code is not stored; embeddings cannot reconstruct source code

**What we don't do:**

- No user code is stored on external servers
- No data is used for AI model training
- No payment card details are stored by Mault (handled entirely by Stripe)

For full details, see our [Privacy Policy](https://mault.ai/privacy/).

## Important Disclosures

- **Backend Connection**: This extension connects to Mault's backend service for authentication and Pro license management.
- **Account Required**: A Mault account is required to use this extension.
- **Mault Core**: All 17 architectural detectors + basic runtime hooks are FREE forever. Advanced runtime hooks require Pro.
- **Mault Pro**: $99 activation + $7.99/month for automated governance, early access, and Production Readiness Kit.
- **Links**: [Privacy Policy](https://mault.ai/privacy/) | [Terms of Service](https://mault.ai/terms/) | [Billing](https://mault.ai/billing/)

---

## License

The Mault VS Code extension is licensed under the [Apache License, Version 2.0](https://github.com/nootan-ai/mault-memory-layer/blob/HEAD/LICENSE).

Use of Mault's cloud services is governed separately by [Mault's Terms of Service](https://mault.ai/terms/).

## Legal & Support

- [Privacy Policy](https://mault.ai/privacy/)
- [Terms of Service](https://mault.ai/terms/)
- [Billing](https://mault.ai/billing/)
- [Cookie Policy](https://mault.ai/cookie-policy/)
- [Support](mailto:support@mault.ai)