# PMAT Pre-commit Hook Quality Gate Issue
**Date**: 2025-10-28
**Severity**: CRITICAL
**Category**: Quality Assurance / Toyota Way Violation
**Status**: OPEN
## Executive Summary
PMAT-generated pre-commit hooks contain "temporarily disabled" quality gate checks (complexity and SATD analysis), violating Toyota Way "Stop the Line" principles. This creates technical debt and allows quality degradation to creep into the codebase.
## Problem Statement
**Root Cause**: `.git/hooks/pre-commit` is auto-generated by PMAT with complexity and SATD checks commented out and marked as "temporarily disabled".
**Evidence** (`.git/hooks/pre-commit` lines 30-55):
```bash
# 1. Complexity analysis (TEMPORARILY DISABLED for PARSER-055 commit)
# TODO: Re-enable after fixing cognitive complexity violations
echo -n " Complexity check... "
echo "⚠️ (temporarily disabled)"
# COMPLEXITY_OUTPUT=$(pmat analyze complexity --max-cyclomatic $PMAT_MAX_CYCLOMATIC_COMPLEXITY --max-cognitive $PMAT_MAX_COGNITIVE_COMPLEXITY 2>&1)
# ... [check code commented out]
# 2. SATD (Self-Admitted Quality Issues) check (TEMPORARILY DISABLED)
# TODO: Fix SATD exclusions for tests.disabled directory
echo -n " SATD check... "
echo "⚠️ (temporarily disabled)"
# SATD_OUTPUT=$(pmat analyze satd 2>&1)
# ... [check code commented out]
```
**Impact**:
- Code can be committed with complexity violations (max cyclomatic/cognitive complexity ≤10)
- SATD comments (TODO, FIXME, HACK) can accumulate unchecked
- Violates CLAUDE.md mandates: "NEVER bypass quality gates", "Zero SATD tolerance"
- Creates false sense of security ("quality gates passing" but checks are disabled)
## Toyota Way Violation
**Principle Violated**: **Stop the Line** - When quality issues arise, halt work and fix root cause
**Wrong Approach** (current state):
1. Quality check fails → Comment it out
2. Mark as "temporarily disabled"
3. Add TODO to fix later
4. Allow degraded quality to persist indefinitely
**Correct Approach** (Toyota Way):
1. Quality check fails → STOP THE LINE
2. Five Whys root cause analysis
3. Fix underlying violations
4. Re-enable check and verify passes
5. Document fix and prevent recurrence
## Five Whys Analysis
**Why are checks temporarily disabled?**
→ Because they were failing and blocking commits
**Why were they failing?**
→ Because codebase has complexity/SATD violations
**Why does codebase have violations?**
→ Because quality standards weren't enforced during development
**Why weren't they enforced?**
→ Because pre-commit hooks had checks disabled
**Why were hooks disabled?**
→ **ROOT CAUSE**: PMAT hook generator defaults to "temporarily disabled" pattern instead of enforcing quality gates
## Proposed Solution
### Option 1: PMAT Configuration-Based Approach (PREFERRED)
PMAT should provide configuration to control hook behavior:
```toml
# .pmat/config.toml
[hooks]
# Enforcement mode: "strict" (fail on ANY violation), "disabled" (skip checks), "warn" (report but allow)
complexity_enforcement = "strict"
satd_enforcement = "strict"
fail_fast = true # Stop at first failure vs report all
[quality]
max_cyclomatic_complexity = 10
max_cognitive_complexity = 10
max_satd_comments = 0 # Zero tolerance for TODO/FIXME/HACK
```
**Regenerate hooks**: `pmat hooks refresh` applies configuration
### Option 2: PMAT Hook Generator Fix (RECOMMENDED)
PMAT `hooks install` command should:
1. Generate hooks with checks **ENABLED by default**
2. If configuration requires disabling checks, **FAIL LOUDLY** with error message:
```
ERROR: Quality gate violations detected during hook generation.
PMAT found existing violations that would cause pre-commit failures:
- Complexity: 12 files exceed max cyclomatic complexity (10)
- SATD: 47 TODO/FIXME/HACK comments found
Toyota Way: DO NOT disable checks. Fix violations first.
To fix:
1. Run: pmat analyze complexity --max-cyclomatic 10
2. Refactor files with violations
3. Run: pmat analyze satd
4. Remove TODO/FIXME/HACK comments (complete work or create tickets)
5. Re-run: pmat hooks install
To bypass (NOT RECOMMENDED): pmat hooks install --force-disable-checks
```
3. Require explicit `--force-disable-checks` flag to generate disabled hooks
4. Log warning to STDOUT when disabled hooks are generated
### Option 3: Ruchy-Specific Immediate Fix
While waiting for PMAT upstream fix:
1. **Document Policy** in CLAUDE.md:
- Quality gates MUST NEVER be "temporarily disabled"
- Fix underlying violations, not bypass checks
- Use `pmat hooks refresh` to regenerate after PMAT fix
2. **Manual Hook Fix** (TEMPORARY - will be overwritten):
```bash
```
3. **Fix Existing Violations**:
- Run `pmat analyze complexity --max-cyclomatic 10`
- Refactor files with complexity > 10
- Run `pmat analyze satd`
- Remove or document all SATD comments
## Acceptance Criteria
**PMAT upstream fix complete when**:
- [ ] `pmat hooks install` generates hooks with checks ENABLED by default
- [ ] Disabled checks require explicit `--force-disable-checks` flag
- [ ] Hook generation fails with actionable error message if violations exist
- [ ] `pmat hooks refresh` regenerates hooks from `.pmat/config.toml`
- [ ] Documentation explains Toyota Way approach (fix violations, not bypass)
**Ruchy immediate fix complete when**:
- [ ] CLAUDE.md documents quality gate enforcement policy
- [ ] All complexity violations fixed (≤10 cyclomatic/cognitive)
- [ ] All SATD comments removed or ticketed
- [ ] Pre-commit hook manually edited to re-enable checks
- [ ] Test commit verifies hooks block violations
## References
- **Toyota Way**: "Stop the Line" principle (Jidoka)
- **CLAUDE.md**: "NEVER bypass quality gates", "Zero SATD tolerance"
- **Pre-commit Hook**: `.git/hooks/pre-commit` lines 1-4 (auto-generated warning)
- **PMAT Commands**: `pmat hooks install`, `pmat hooks refresh`
## Action Items
**Immediate (Ruchy Project)**:
1. Create tracking issue (this document)
2. Update CLAUDE.md with quality gate enforcement policy
3. Fix existing complexity violations
4. Remove or ticket existing SATD comments
5. Manually re-enable checks in pre-commit hook
6. Verify with test commit
**Upstream (PMAT Project)**:
1. Open GitHub issue in PMAT repository
2. Propose configuration-based approach
3. Implement hook generator improvements
4. Add Toyota Way documentation
5. Release PMAT version with fix
6. Update Ruchy to use fixed PMAT version
---
**Created**: 2025-10-28
**Author**: Quality Assurance Team
**Toyota Way Principle**: Stop the Line - Fix root causes, never bypass quality