# SEF-Agents Compliance & PR Review Metrics

> **Generated by:** Forensic Engineer
> **Date:** 2026-01-09
> **Purpose:** Enterprise-grade compliance standards for code quality, security, and technical debt

---

## Executive Summary

SEF-Agents enforces production-grade quality standards through automated scanning and validation. This document defines **measurable compliance metrics** and **PR review criteria** that must be met before code merges.

**Key Principle:** Zero tolerance for **CRITICAL** issues. **HIGH** severity issues require remediation plan.

---

## 1. Code Quality Metrics (pe_rules)

### 1.1 Exception Handling

| Rule ID | Metric | Severity | Target | Enforcement |
|---------|--------|----------|--------|-------------|
| **E001** | Bare `except:` clauses | 🔴 CRITICAL | **0** violations | ❌ **BLOCKS PR** |
| **E002** | `except Exception` without re-raise | 🔴 CRITICAL | **0** violations | ❌ **BLOCKS PR** |

**Rationale:** Bare exceptions catch system exits (`KeyboardInterrupt`, `SystemExit`) and mask critical failures.

**Remediation:** Use specific exception types (e.g., `ValueError`, `TypeError`) and include re-raise logic where appropriate.

---

### 1.2 Type Hints

| Rule ID | Metric | Severity | Target | Enforcement |
|---------|--------|----------|--------|-------------|
| **T001** | Missing return type hints | 🟠 HIGH | **< 5%** of public functions | ⚠️ **Requires plan** |

**Rationale:** Type hints enable static analysis, catch bugs at dev time, and improve IDE support.

**Remediation:** Add type annotations to function signatures with return types and parameter types.

**Exclusions:** Private methods (`_method`), dunder methods (`__init__`)

---

### 1.3 Documentation

| Rule ID | Metric | Severity | Target | Enforcement |
|---------|--------|----------|--------|-------------|
| **D001** | Missing docstrings (public functions) | 🟡 MEDIUM | **< 10%** of public APIs | 📋 **Backlog** |
| **D002** | Placeholder docstrings (`TODO`, `...`) | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **D003** | Missing `Args:` section (functions with params) | 🟡 MEDIUM | **< 15%** | 📋 **Backlog** |
| **D004** | Missing module docstring | 🟡 MEDIUM | **< 20%** of modules | 📋 **Backlog** |

**Remediation:** Add Google/Numpy style docstrings with `Args:`, `Returns:`, and `Raises:` sections.

---

### 1.4 Logging Standards

| Rule ID | Metric | Severity | Target | Enforcement |
|---------|--------|----------|--------|-------------|
| **L001** | `print()` statements in production code | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **L002** | `logging.*` instead of `structlog` | 🟡 MEDIUM | **0** violations | 📋 **Backlog** |
| **L003** | f-strings in logger calls | 🟡 MEDIUM | **< 10%** | 📋 **Backlog** |

**Rationale:** Structured logging (structlog) enables log aggregation, filtering, and observability.

**Remediation:** Replace `print()` and standard `logging` with `structlog`. Use structured key-value pairs instead of f-strings.

---

### 1.5 Import Organization

| Rule ID | Metric | Severity | Target | Enforcement |
|---------|--------|----------|--------|-------------|
| **I001** | Import order violations | 🟡 MEDIUM | **0** violations | 📋 **Backlog** |

**Required Order:**
1. **Standard library** (e.g., `os`, `sys`, `pathlib`)
2. **Third-party** (e.g., `structlog`, `fastapi`)
3. **Local** (e.g., `sef_agents.*`)

**Remediation:** Organize imports in the specified order with blank lines separating each section.

---

## 2. Frontend Quality Metrics

### 2.1 TypeScript/JavaScript Standards

| Rule ID | Metric | Severity | Target | Enforcement |
|---------|--------|----------|--------|-------------|
| **TS-ANY** | `: any` type usage | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **TS-IGNORE** | `@ts-ignore` / `@ts-nocheck` | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **TS-CONSOLE** | `console.log()` in production | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **TS-EMPTY** | Empty catch blocks | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **TS-RETURN** | Missing return type annotations | 🟡 MEDIUM | **< 10%** of functions | 📋 **Backlog** |
| **TS-NULLABLE** | Non-null assertion (`!`) overuse | 🟡 MEDIUM | **< 5%** | 📋 **Backlog** |
| **TS-PROMISE** | Promises not awaited (`.then()` chains) | 🟡 MEDIUM | **< 10%** | 📋 **Backlog** |
| **JS-VAR** | `var` instead of `let`/`const` | 🟡 MEDIUM | **0** violations | 📋 **Backlog** |
| **JS-EVAL** | `eval()` usage | 🔴 CRITICAL | **0** violations | ❌ **BLOCKS PR** |
| **JS-INNERHTML** | `.innerHTML` assignment (XSS risk) | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **JS-EQUALITY** | `==` instead of `===` | 🟡 MEDIUM | **0** violations | 📋 **Backlog** |
| **JS-MUTATION** | Direct state mutation | 🔴 CRITICAL | **0** violations | ❌ **BLOCKS PR** |

**Rationale:** TypeScript's type system prevents runtime errors. `any` defeats this. `console.log` leaks to production. Direct mutations break React/Redux.

**Remediation:** Use specific types, structured logging libraries (pino, winston), and immutable patterns (spread, map, filter).

---

### 2.2 React-Specific Standards

| Rule ID | Metric | Severity | Target | Enforcement |
|---------|--------|----------|--------|-------------|
| **REACT-KEY** | Missing `key` prop in lists | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **REACT-STATE** | Direct state mutation | 🔴 CRITICAL | **0** violations | ❌ **BLOCKS PR** |
| **REACT-DEPS** | useEffect missing dependencies | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **REACT-DOM** | Direct DOM manipulation | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **REACT-LIFECYCLE** | Deprecated lifecycle methods | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **REACT-INLINE** | Inline styles | 🟡 MEDIUM | **< 10%** of components | 📋 **Backlog** |
| **REACT-ANON** | Anonymous function props | 🟡 MEDIUM | **< 20%** | 📋 **Backlog** |
| **REACT-PROPS** | Component props count | 🟡 MEDIUM | ≤ 5 props per component | 📋 **Backlog** |
| **REACT-HOOKS** | Hooks per component | 🟡 MEDIUM | ≤ 4 hooks per component | 📋 **Backlog** |
| **REACT-SIZE** | Component size | 🟡 MEDIUM | ≤ 100 lines | 📋 **Backlog** |
| **REACT-DRILLING** | Prop drilling depth | 🟡 MEDIUM | ≤ 2 levels | 📋 **Backlog** |

**Rationale:** Missing keys cause performance issues. State mutations break React's reconciliation. Too many props/hooks indicate poor component design.

**Remediation:** Add unique keys to lists. Use `useState` setters. Extract logic to custom hooks. Use Context API for deep prop passing.

---

### 2.3 Angular-Specific Standards

| Rule ID | Metric | Severity | Target | Enforcement |
|---------|--------|----------|--------|-------------|
| **NG-SUBSCRIBE** | Subscriptions without unsubscribe | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **NG-ANY** | `$any()` in templates | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **NG-DOM** | Direct DOM access | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **NG-TRACKBY** | `*ngFor` without trackBy | 🟡 MEDIUM | **< 10%** | 📋 **Backlog** |
| **NG-HTTP** | Deprecated Http module | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **NG-COMPAT** | rxjs-compat usage | 🟡 MEDIUM | **0** violations | 📋 **Backlog** |
| **NG-METHODS** | Component methods count | 🟡 MEDIUM | ≤ 7 methods per component | 📋 **Backlog** |
| **NG-SERVICES** | Injected services count | 🟡 MEDIUM | ≤ 4 services per component | 📋 **Backlog** |
| **NG-I18N** | Hardcoded strings | 🟡 MEDIUM | **< 20%** of templates | 📋 **Backlog** |

**Rationale:** Unsubscribed observables cause memory leaks. Direct DOM access bypasses Angular's change detection. Too many services indicate poor separation of concerns.

**Remediation:** Use `async` pipe, `takeUntil`, or `ngOnDestroy`. Use ViewChild/Renderer2. Migrate to HttpClient. Add trackBy functions.

---

## 3. Compliance Validation

### 2.1 Curator Protocol (Code Comments)

| Pattern | Violation Type | Severity | Target | Enforcement |
|---------|---------------|----------|--------|-------------|
| Code-echoing comments | Curator protocol violation | 🟡 MEDIUM | **0** violations | 📋 **Backlog** |
| Docstring fluff | Token waste | 🟡 MEDIUM | **0** violations | 📋 **Backlog** |

**Forbidden Patterns:**
- `# increment counter` (code-echoing)
- `# set value to X` (code-echoing)
- `# loop through items` (code-echoing)
- `"This function is designed to..."` (docstring fluff)
- `"It is important to note that..."` (docstring fluff)
- `"In order to..."` (use "to" instead)

**Rationale:** Comments should explain **WHY**, not **WHAT**. Code should be self-documenting.

**Remediation:** Replace code-echoing comments with contextual explanations. Remove verbose docstring phrases.

---

### 2.2 MCP Tool Docstrings

| Rule ID | Metric | Severity | Target | Enforcement |
|---------|--------|----------|--------|-------------|
| **MCP001** | `@mcp.tool()` without docstring | 🔴 CRITICAL | **0** violations | ❌ **BLOCKS PR** |

**Rationale:** FastMCP uses docstrings as tool descriptions in the MCP protocol.

**Remediation:** Add comprehensive docstrings to all MCP tools with `Args:` and `Returns:` sections.

---

### 2.3 TypeScript Strict Typing

| Rule ID | Metric | Severity | Target | Enforcement |
|---------|--------|----------|--------|-------------|
| **TS001** | `: any` type usage | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |

**Remediation:** Replace `: any` with specific types (e.g., `string[]`, `number`, custom interfaces).

---

## 3. Technical Debt Metrics

### 3.1 Debt Categories

| Debt Type | Severity | Target | Enforcement |
|-----------|----------|--------|-------------|
| **TODO/FIXME** comments | 🟡 MEDIUM | **< 20** per 10k LOC | 📋 **Backlog** |
| **Deprecated imports** | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **High complexity** (cyclomatic > 12) | 🟠 HIGH | **< 5%** of functions | ⚠️ **Requires plan** |
| **Long functions** (> 50 LOC) | 🟡 MEDIUM | **< 10%** of functions | 📋 **Backlog** |
| **Deep nesting** (> 3 levels) | 🟡 MEDIUM | **< 10%** of functions | 📋 **Backlog** |

---

### 3.2 Complexity Thresholds

| Metric | Threshold | Rationale |
|--------|-----------|-----------|
| **Cyclomatic Complexity** | ≤ 12 | Maintainable, testable code |
| **Function Length** | ≤ 50 lines | Single responsibility principle |
| **Nesting Depth** | ≤ 3 levels | Readable, avoid arrow anti-pattern |
| **File Length** | ≤ 300 lines | Encourages module extraction |
| **Comment Ratio** | ≤ 0.4 | Avoid verbose comments |
| **Class-to-Function Ratio** | ≤ 0.5 | Avoid over-abstraction |

**Remediation:** Refactor complex functions into smaller, focused units. Use early returns to reduce nesting. Extract helper methods.

---

### 3.3 AI Anti-Patterns

| Pattern | Severity | Threshold | Enforcement |
|---------|----------|-----------|-------------|
| **Over-abstraction** | 🟡 MEDIUM | Class/Function ratio > 0.5 | 📋 **Backlog** |
| **Generic naming** | 🔵 LOW | < 10% of identifiers | ℹ️ **Info** |
| **Copy-paste blocks** | 🟠 HIGH | Similarity > 85% | ⚠️ **Requires plan** |
| **Verbose comments** | 🔵 LOW | Comment ratio > 0.4 | ℹ️ **Info** |

**Generic Names to Avoid:**
`data`, `result`, `temp`, `tmp`, `handler`, `manager`, `helper`, `utils`, `misc`, `stuff`, `thing`, `obj`, `val`, `var`, `foo`, `bar`, `baz`

---

## 4. Security Metrics

### 4.1 Security Scans

| Scan Type | Severity | Target | Enforcement |
|-----------|----------|--------|-------------|
| **Secret detection** | 🔴 CRITICAL | **0** exposed secrets | ❌ **BLOCKS PR** |
| **Network imports** (unsafe) | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **Outbound URLs** (unregistered) | 🟡 MEDIUM | **0** violations | 📋 **Backlog** |
| **Dependency vulnerabilities** | 🔴 CRITICAL | **0** critical CVEs | ❌ **BLOCKS PR** |
| **Unsafe file operations** | 🟠 HIGH | **0** violations | ⚠️ **Requires plan** |
| **License violations** | 🟠 HIGH | **0** GPL/AGPL in proprietary | ⚠️ **Requires plan** |

---

### 4.2 Secret Detection Patterns

**Blocked Patterns:**
- API keys: `api[_-]?key\s*=\s*['"][^'"]+['"]`
- Passwords: `password\s*=\s*['"][^'"]+['"]`
- Tokens: `token\s*=\s*['"][^'"]+['"]`
- AWS credentials: `AKIA[0-9A-Z]{16}`
- Private keys: `-----BEGIN (RSA|DSA|EC) PRIVATE KEY-----`

**Remediation:** Use environment variables or secret management systems (e.g., Azure Key Vault, AWS Secrets Manager).

---

### 4.3 Network Security

**Unsafe Imports:**
- `urllib.request` (use `httpx` or `requests`)
- `socket` (requires justification)
- `ftplib`, `telnetlib` (deprecated protocols)

**External API Registration:**
All outbound API calls must be registered in `EXTERNAL_APIS.md`.

---

## 5. PR Review Criteria

### 5.1 Blocking Conditions

**PR MUST NOT MERGE if:**

| Condition | Severity | Rationale |
|-----------|----------|-----------|
| ≥ 1 **CRITICAL** issue | 🔴 CRITICAL | Production stability risk |
| ≥ 1 exposed secret | 🔴 CRITICAL | Security breach |
| ≥ 1 critical CVE | 🔴 CRITICAL | Known vulnerability |
| ≥ 1 bare `except:` | 🔴 CRITICAL | Masks system failures |
| ≥ 1 MCP tool without docstring | 🔴 CRITICAL | Breaks MCP protocol |

---

### 5.2 Remediation Required

**PR requires remediation plan if:**

| Condition | Severity | Action |
|-----------|----------|--------|
| ≥ 5 **HIGH** severity issues | 🟠 HIGH | Create remediation story |
| ≥ 10 **MEDIUM** severity issues | 🟡 MEDIUM | Create tech debt ticket |
| Complexity > 12 in new code | 🟠 HIGH | Refactor before merge |
| Missing type hints on new public APIs | 🟠 HIGH | Add type hints |

---

### 5.3 Quality Gates

| Gate | Metric | Target | Enforcement |
|------|--------|--------|-------------|
| **Code Coverage** | Line coverage | ≥ 80% | ⚠️ **Recommended** |
| **Test Pass Rate** | All tests | 100% | ❌ **BLOCKS PR** |
| **Linter** | Ruff/ESLint | 0 errors | ❌ **BLOCKS PR** |
| **Type Checker** | mypy/TypeScript | 0 errors | ⚠️ **Recommended** |
| **Security Scan** | All checks | PASS | ❌ **BLOCKS PR** |

---

## 6. Enforcement Levels

### 6.1 Severity Definitions

| Severity | Symbol | Enforcement | SLA |
|----------|--------|-------------|-----|
| **CRITICAL** | 🔴 | ❌ **BLOCKS PR** | Fix immediately |
| **HIGH** | 🟠 | ⚠️ **Requires plan** | Fix within sprint |
| **MEDIUM** | 🟡 | 📋 **Backlog** | Fix within quarter |
| **LOW** | 🔵 | ℹ️ **Info** | Best effort |

---

### 6.2 Automated Enforcement

**Pre-commit Hooks:**
- Secret scanning
- Linting (Ruff, ESLint)
- Import sorting

**CI/CD Pipeline:**
- Security scan (all checks)
- Code quality scan
- Debt scan
- Test execution
- Coverage report

**PR Review Bot:**
- Compliance validation
- Complexity analysis
- Debt trend analysis

---

## 7. Metrics Dashboard

### 7.1 Health Score Calculation

```
Health Score = 100 - (
    CRITICAL * 10 +
    HIGH * 3 +
    MEDIUM * 1 +
    LOW * 0.1
)
```

**Thresholds:**
- **≥ 90:** ✅ Excellent
- **70-89:** ⚠️ Good
- **50-69:** 🟡 Needs Improvement
- **< 50:** 🔴 Critical

---

### 7.2 Trend Metrics

| Metric | Frequency | Target Trend |
|--------|-----------|--------------|
| **Debt Count** | Weekly | ⬇️ Decreasing |
| **Critical Issues** | Daily | 0 |
| **Code Coverage** | Per PR | ⬆️ Increasing |
| **Complexity Average** | Weekly | ⬇️ Decreasing |
| **Security Violations** | Per PR | 0 |

---

## 8. Exemptions & Overrides

### 8.1 Exemption Process

**Exemptions allowed for:**
- Legacy code (with migration plan)
- Third-party integrations (with justification)
- Performance-critical code (with benchmarks)

**Approval Required:**
- **CRITICAL:** Tech Lead + Security Owner
- **HIGH:** Tech Lead
- **MEDIUM:** PR Reviewer

**Documentation:**
Add `# sef-ignore: RULE_ID - Justification` above violation.

---

### 8.2 Intentional Ignores

**File-level:** `# sef-ignore-file: Autogenerated code`

**Line-level:** `# sef-ignore: E001 - Catching all exceptions for graceful degradation`

---

## 9. Tool Reference

### 9.1 Available Scanners

| Tool | Purpose | Output |
|------|---------|--------|
| `scan_code_quality` | pe_rules enforcement | `sef-reports/code_quality.md` |
| `scan_debt` | Technical debt detection | `sef-reports/debt_report.md` |
| `run_security_audit` | Security compliance | `sef-reports/security/security_audit_*.md` |
| `validate_compliance` | File-level validation | `sef-reports/{agent}/compliance_*.md` |
| `scan_health` | Orchestrated health check | `sef-reports/health_report.md` |

---

### 9.2 CLI Commands

```bash
# Run all scans
uv run python -m sef_agents.security_scan

# Code quality only
uv run python -c "from sef_agents.tools.code_quality_scanner import scan_code_quality; scan_code_quality('.')"

# Debt scan with summary
uv run python -c "from sef_agents.tools.debt_scanner import scan_debt; scan_debt('.', summary=True)"

# Health scan (all scanners)
uv run python -c "from sef_agents.tools.health_scanner import scan_health; scan_health('.')"
```

---

## 10. References

### 10.1 Source Files

- [compliance.py](file:///Users/mthangaraj/my_projects/sage/sef-agents/src/sef_agents/tools/compliance.py) - Compliance validation
- [code_quality_scanner.py](file:///Users/mthangaraj/my_projects/sage/sef-agents/src/sef_agents/tools/code_quality_scanner.py) - pe_rules enforcement
- [debt_scanner.py](file:///Users/mthangaraj/my_projects/sage/sef-agents/src/sef_agents/tools/debt_scanner.py) - Technical debt detection
- [security_scan.py](file:///Users/mthangaraj/my_projects/sage/sef-agents/src/sef_agents/security_scan.py) - Security audit orchestrator

### 10.2 Configuration Files

- [python.yaml](file:///Users/mthangaraj/my_projects/sage/sef-agents/src/sef_agents/config/languages/python.yaml) - Python debt patterns
- [ai_patterns.yaml](file:///Users/mthangaraj/my_projects/sage/sef-agents/src/sef_agents/config/ai_patterns.yaml) - AI anti-pattern detection

---

## Appendix A: Quick Reference

### Severity Symbols
- 🔴 **CRITICAL** - Blocks PR
- 🟠 **HIGH** - Requires remediation plan
- 🟡 **MEDIUM** - Backlog
- 🔵 **LOW** - Informational

### Rule ID Prefixes
- **E0xx** - Exception handling
- **T0xx** - Type hints
- **D0xx** - Documentation
- **L0xx** - Logging
- **I0xx** - Imports
- **MCP0xx** - MCP tools
- **TS0xx** - TypeScript

### Enforcement Actions
- ❌ **BLOCKS PR** - Cannot merge
- ⚠️ **Requires plan** - Remediation story needed
- 📋 **Backlog** - Tech debt ticket
- ℹ️ **Info** - Best effort

---

**Document Version:** 1.0
**Last Updated:** 2026-01-09
**Maintained By:** SEF-Agents Forensic Engineer
