# PMAT Documentation

Welcome to the PMAT (Pragmatic AI MCP Agent Toolkit) documentation.

## 📚 Documentation Structure

### Core Documentation
- **[SPECIFICATION.md](./SPECIFICATION.md)** - Complete system specification (source of truth)
- **[CLAUDE_CODE_AGENT.md](./CLAUDE_CODE_AGENT.md)** - Claude Code Agent Mode user guide (v2.12.0)
- **[DISTRIBUTION_STATUS.md](./DISTRIBUTION_STATUS.md)** - Multi-ecosystem distribution status and automation
- **[DOCUMENTATION_STRUCTURE.md](./DOCUMENTATION_STRUCTURE.md)** - Documentation organization guide

### Active Documentation

#### Architecture & Design
- **[architecture/](./architecture/)** - System architecture and design decisions
  - [ARCHITECTURE.md](./architecture/ARCHITECTURE.md) - High-level architecture overview
  - [decisions/](./architecture/decisions/) - Architecture Decision Records (ADRs)

#### Development
- **[execution/](./execution/)** - Sprint planning and execution
  - [roadmap.md](./execution/roadmap.md) - Development roadmap with task tracking
  - [quality-gates.md](./execution/quality-gates.md) - Quality enforcement standards
  - [velocity.json](./execution/velocity.json) - Sprint velocity metrics

#### Features
- **[features/](./features/)** - Feature documentation
  - [README.md](./features/README.md) - Feature overview
  - **[SCAFFOLDING-AND-MAINTENANCE.md](./features/SCAFFOLDING-AND-MAINTENANCE.md)** - **🆕 v2.139.0** Project Scaffolding & Maintenance System (Complete Guide)
  - **[SEMANTIC-SEARCH-GUIDE.md](./SEMANTIC-SEARCH-GUIDE.md)** - **🆕 v2.159.0** Semantic Code Search - Complete User Guide
  - [claude-agent-sdk-guide.md](./claude-agent-sdk-guide.md) - Claude Agent SDK Integration Guide
  - [deep-wasm-usage.md](./deep-wasm-usage.md) - Deep WASM Pipeline Inspection (Phases 1-2.7 Complete)
  - [mutation-testing.md](./mutation-testing.md) - Mutation Testing with ML Prediction
  - Individual feature guides for each major capability

#### User Guides
- **[guides/](./guides/)** - User and integration guides
  - [interfaces-overview.md](./guides/interfaces-overview.md) - CLI, MCP, HTTP interfaces
  - [refactor-auto-guide.md](./guides/refactor-auto-guide.md) - Automated refactoring guide
  - [github-actions-quality-gate.md](./guides/github-actions-quality-gate.md) - CI/CD integration

#### Dogfooding
- **[dogfooding/](./dogfooding/)** - Real-world validation of PMAT features
  - [README.md](./dogfooding/README.md) - Dogfooding overview and command reference
  - [v2.139.0-INTEGRATION-SHOWCASE.md](./dogfooding/v2.139.0-INTEGRATION-SHOWCASE.md) - **🆕** Complete v2.139.0 integration showcase
  - [SPRINT-19-DOGFOODING-RESULTS.md](./dogfooding/SPRINT-19-DOGFOODING-RESULTS.md) - Sprint 19 findings

#### Operations
- **[operations/](./operations/)** - Operational documentation
  - [configuration.md](./operations/configuration.md) - Configuration guide
  - [error-handling.md](./operations/error-handling.md) - Error handling patterns
  - [telemetry.md](./operations/telemetry.md) - Monitoring and telemetry

#### Quality & Testing
- **[quality/](./quality/)** - Quality standards and metrics
  - [standards.md](./quality/standards.md) - Code quality standards
- **[testing/](./testing/)** - Testing documentation
  - [property-based.md](./testing/property-based.md) - Property-based testing guide
  - [integration.md](./testing/integration.md) - Integration testing
  - [performance.md](./testing/performance.md) - Performance testing

#### Specifications
- **[specifications/](./specifications/)** - Feature specifications
  - [roadmap-todo-quality-gate-spec.md](./specifications/components/work-management.md) - Roadmap management spec
  - [publish-mcp-registry.md](./specifications/components/mcp-protocol.md) - MCP Registry publishing specification

### Release Information
- **[release-process.md](./release-process.md)** - Release workflow and procedures
- **[release_notes/](./release_notes/)** - Recent release notes (v2.x+)
- **[/CHANGELOG.md](../CHANGELOG.md)** - Complete version history

### Development Planning
- **[todo/](./todo/)** - Future development specifications
  - Active specifications for upcoming features
  - [archive/](./todo/archive/) - Completed or deprecated specs

### Reference
- **[cli-reference.md](./cli-reference.md)** - CLI command reference
- **[bugs/](./bugs/)** - Known issues and bug reports
  - [archived/](./bugs/archived/) - Resolved issues

## 🗄️ Archived Documentation

Historical and deprecated documentation has been moved to the archive:
- **[archive/](./archive/)** - Archived documentation
  - [ARCHIVE_INDEX.md](./archive/ARCHIVE_INDEX.md) - Archive navigation guide
  - [pre-v2.0/](./archive/pre-v2.0/) - Pre-2.0 version documentation
  - Historical release notes, implementation docs, and deprecated features

## 🚀 Quick Start

1. **New Users**: Start with [SPECIFICATION.md](./SPECIFICATION.md) for system overview
2. **Developers**: Check [execution/roadmap.md](./execution/roadmap.md) for current tasks
3. **Contributors**: Review [quality/standards.md](./quality/standards.md) for quality requirements
4. **Integrators**: See [guides/interfaces-overview.md](./guides/interfaces-overview.md) for API details

## 📖 Getting Started with PMAT

PMAT (Pragmatic Multi-language Analysis Tool) analyzes codebases across 14+ languages to provide:

- **Technical Debt Grading (TDG)**: Letter grades (A+ to F) for code quality
- **Complexity Analysis**: Cyclomatic complexity, cognitive complexity, nesting depth
- **Dead Code Detection**: Unused functions, variables, imports
- **SATD Analysis**: Self-Admitted Technical Debt annotations (TODO, FIXME, HACK)
- **Architecture Insights**: Dependency graphs, module relationships
- **MCP Integration**: AI-powered code analysis via Model Context Protocol
- **Quality Gates**: Pre-commit hooks enforcing quality standards

### Quick Start Commands

```bash
# Analyze current directory
pmat analyze .

# Get Technical Debt Grade
pmat analyze tdg .

# Generate comprehensive context for AI assistants
pmat context

# Run quality gate checks
pmat quality-gate --threshold B+
```

### 📚 Comprehensive User Documentation

For detailed guides, examples, and best practices, see the **[PMAT Book](https://github.com/paiml/pmat-book)** - the official comprehensive documentation with 28 chapters covering all PMAT features, including:

- Installation and setup guides
- Complete command reference
- Real-world examples with TDD validation
- Multi-language project tutorials
- MCP integration guides
- Quality-driven development workflows

**New users should start with the PMAT Book for step-by-step tutorials and practical examples.**

## 📖 Documentation Standards

All documentation follows these principles:
- **Single Source of Truth**: SPECIFICATION.md is the authoritative reference
- **Version Synchronized**: Documentation updates required with code changes
- **Quality Enforced**: Pre-commit hooks ensure documentation quality
- **Toyota Way Aligned**: Continuous improvement (Kaizen) approach

## 🔗 External Resources

- **Repository**: [github.com/paiml/paiml-mcp-agent-toolkit](https://github.com/paiml/paiml-mcp-agent-toolkit)
<!-- PMAT not yet published to crates.io: - **Crates.io**: <!-- PMAT not yet published to crates.io: [crates.io/crates/pmat](https://crates.io/crates/pmat) --> -->
- **MCP Registry**: [registry.modelcontextprotocol.io (io.github.paiml/pmat-agent)](https://registry.modelcontextprotocol.io/v0/servers?search=pmat)
- **Homepage**: [paiml.com](https://paiml.com)

## 🎯 Featured Capabilities

### Deep WASM Pipeline Inspection
Complete Rust/Ruchy → WebAssembly analysis pipeline with bidirectional tracing. **[Full Guide →](./deep-wasm-usage.md)**

- ✅ **Phase 1-2.7 Complete**: WASM binary parsing, DWARF correlation, mutation testing, unified parser
- 🔬 WASM binary parser with zero-copy analysis (wasmparser)
- 🗺️ DWARF v5 bidirectional source mapping (gimli)
- 🧬 WASM mutation testing with 3 operators (180 tests passing)
- ⚡ Unified WASM parser with 40-50% performance improvement
- 🎭 Ruchy language support for actor systems
- 📋 Phase 3 scoped: Runtime analysis, profiling, security scanning

### Semantic Code Search ✨ NEW (v2.159.0)
**AI-powered code search using natural language and vector embeddings.** **[Full Guide →](./SEMANTIC-SEARCH-GUIDE.md)**

- 🔍 **Natural language search** - Find code by meaning: "authentication middleware"
- 🧠 **Hybrid search** - Combines keyword + semantic understanding (Reciprocal Rank Fusion)
- 🔎 **Find similar code** - Discover duplicates and refactoring opportunities
- 🗂️ **Auto-clustering** - Group code by semantic similarity (K-means, hierarchical, DBSCAN)
- 📊 **Topic extraction** - Identify architectural patterns and themes
- 🤖 **MCP integration** - 4 tools for AI assistants (Claude Code, Cursor)
- 🌐 **Multi-language** - Rust, TypeScript, Python, C/C++, Go
- ⚡ **Fast** - <150ms hybrid search on 10K chunks
- 💰 **Low cost** - $0.01-$0.05 for most codebases (one-time)
- 📦 **Published** - Available on crates.io v2.159.0

**Quick Start:**
```bash
export OPENAI_API_KEY="sk-..."
pmat embed sync .
pmat semantic search "authentication logic"
pmat analyze cluster --method kmeans --k 5
```

### Mutation Testing Engine
Empirical mutation testing with actual test execution and optional ML prediction. **[Full Guide →](./mutation-testing.md)**

- ⚡ **20× faster than cargo-mutants** with smart test filtering (v2.135.0)
- ✨ **Properly formatted output** using prettyplease (v2.136.0)
- 🔧 **CRITICAL BUG FIXED**: File corruption issue resolved (Issue #64, v2.136.0)
- 🧪 Real test execution with `cargo test --lib` on each mutant
- 🔀 6 mutation operators (AOR, ROR, COR, UOR, CRR, SDL)
- 🌐 Multi-language support (Rust, WASM/WAT)
- 🧠 Optional ML prediction with decision tree classifier (75-95% accuracy)
- 🚀 Distributed execution with work-stealing queue
- 📈 CI/CD learning and auto-training (50 sample threshold)

### TypeScript/JavaScript Mutation Testing ✨ NEW (v2.144.0)
**Production-ready AST-based mutation testing for TypeScript and JavaScript.** **[Full Guide →](./features/TYPESCRIPT-MUTATION-TESTING.md)**

- 🎯 **80%+ mutation scores achievable** - Quantify test suite quality
- ⚡ **Fast generation** - 67 mutants in 14ms using tree-sitter AST
- 🔍 **Real test execution** - Works with jest, vitest, mocha
- 🧬 **5 mutation operators** - Arithmetic, equality, optional chaining, nullish coalescing, async/await
- 📊 **Identifies test gaps** - Surviving mutants show actual weaknesses
- 🔄 **Full automation** - Source → mutants → tests → score
- 🏗️ **Language-agnostic architecture** - Reusable for Python, Go, C++

### Python Mutation Testing ✨ NEW (v2.152.0)
**Production-ready AST-based mutation testing for Python 3.6+.** **[Full Guide →](./features/PYTHON-MUTATION-TESTING.md)**

- 🎯 **80%+ mutation scores achievable** - Validate test suite quality
- ⚡ **Ultra-fast generation** - 56 mutants in 5ms using tree-sitter AST
- 🔍 **Real test execution** - Works with pytest and unittest
- 🧬 **5 mutation operators** - Binary (AOR), relational (ROR), logical (LOR), identity (is/is not), membership (in/not in)
- 📊 **Identifies test gaps** - Surviving mutants reveal actual weaknesses
- 🔄 **Full automation** - Source → mutants → tests → score
- 🏗️ **Language-agnostic architecture** - Shared with TypeScript implementation

### Go Mutation Testing ✨ NEW (v2.153.0)
**Production-ready AST-based mutation testing for Go 1.21+.** **[Full Guide →](./features/GO-MUTATION-TESTING.md)**

- 🎯 **80%+ mutation scores achievable** - Validate test suite quality
- ⚡ **FASTEST generation** - <3ms for ~60 mutants using tree-sitter AST
- 🔍 **Real test execution** - Works with standard `go test`
- 🧬 **6 mutation operators** - Binary (AOR), relational (ROR), logical (LOR), **bitwise (BOR)**, **unary (UOR)**, **assignment**
- 🔷 **Go-specific features** - Bitwise ops, compound assignment, unary operators
- 📊 **Identifies test gaps** - Surviving mutants reveal actual weaknesses
- 🔄 **Full automation** - Source → mutants → tests → score
- 🏗️ **Language-agnostic architecture** - Shared with TypeScript/Python

### C++ Mutation Testing ✨ NEW (v2.154.0)
**Production-ready AST-based mutation testing for C++17+.** **[Full Guide →](./features/CPP-MUTATION-TESTING.md)**

- 🎯 **80%+ mutation scores achievable** - Quantify test suite quality
- ⚡ **Fast generation** - ~5ms for ~75 mutants using tree-sitter AST
- 🔍 **Real test execution** - Works with CMake/CTest and Google Test
- 🧬 **7 mutation operators** - Binary (AOR), relational (ROR), logical (LOR), **bitwise (BOR)**, **unary (UOR)**, **pointer (POR)**, **member access (MAR)**
- 🔷 **C++-specific features** - Pointer operators, member access, pre/post increment
- 📊 **Identifies test gaps** - Surviving mutants reveal actual weaknesses
- 🔄 **Full automation** - Source → mutants → tests → score
- 🏗️ **Language-agnostic architecture** - Shared with TypeScript/Python/Go

---

*Last Updated: 2025-10-10 | Version: 2.159.0*