---
id: kb-003
title: Project Alignment - Decision Matrix
scope:
  type: project
  id: 4sgm
purpose: alignment-decision-matrix
tags:
  - infrastructure
  - decision-matrix
  - alignment
topics:
  - project-management
  - architecture
version: 1
created: 2025-11-26
updated: 2025-11-26
author: droid-agent
status: final
related_ids:
  - kb-002
  - kb-004
external_refs: []
---

# Project Alignment - Decision Matrix

## Visual Comparison Grid

### 1️⃣ TECHNOLOGY STACK

```
┌─────────────────────────┬──────────────────┬──────────────────┐
│ Component               │ atomsAgent       │ atoms-mcp-prod   │
├─────────────────────────┼──────────────────┼──────────────────┤
│ Language                │ Python 3.11-3.14 │ Python 3.12      │
│ Framework               │ FastAPI          │ FastMCP          │
│ Database                │ Supabase (full)  │ Supabase (lite)  │
│ Cache                   │ Redis/Upstash    │ Upstash only     │
│ Package Manager         │ uv               │ uv               │
│ Build System            │ hatchling        │ hatchling        │
└─────────────────────────┴──────────────────┴──────────────────┘

RECOMMENDATION: Pin Python to 3.12 in atomsAgent
```

### 2️⃣ TEST INFRASTRUCTURE

```
┌─────────────────────────────┬─────────────┬──────────────┐
│ Aspect                      │ atomsAgent  │ atoms-mcp    │
├─────────────────────────────┼─────────────┼──────────────┤
│ Test Framework              │ pytest ✅   │ pytest ✅    │
│ Async Support               │ asyncio ✅  │ asyncio ✅   │
│ Test Markers                │ 60+         │ 40+          │
│ Coverage Reporting          │ ❌ Missing  │ ✅ 95%       │
│ Enhanced CI Reporting       │ ❌ No       │ ✅ Yes       │
│ Process Isolation           │ ✅ Forked   │ ⚠️ Basic     │
│ Benchmark Plugin            │ ✅ Yes      │ ❌ No        │
│ Parallel Execution          │ ✅ xdist    │ ✅ xdist     │
│ Flaky Test Retry            │ ✅ Yes      │ ⚠️ No        │
└─────────────────────────────┴─────────────┴──────────────┘

RECOMMENDATION: Copy enhanced-testing.yml from atoms-mcp-prod
                Add missing plugins to atoms-mcp-prod
```

### 3️⃣ CI/CD MATURITY

```
Score: 0-10 (10 = excellent)

atomsAgent                          atoms-mcp-prod
├─ Unit Tests        ░░░░░░░░░░    ├─ Unit Tests        █████████░
├─ Integration Tests  ░░░░░░░░░░    ├─ Integration Tests  █████████░
├─ E2E Tests         ░░░░░░░░░░    ├─ E2E Tests         █████████░
├─ Coverage Report    ░░░░░░░░░░    ├─ Coverage Report    ██████████
├─ Performance Tests  ██████░░░░    ├─ Performance Tests  ████░░░░░░
├─ Load Tests        ██████░░░░    ├─ Load Tests        ░░░░░░░░░░
├─ Security Tests     ░░░░░░░░░░    ├─ Security Tests     ████████░░
├─ Artifact Upload    ░░░░░░░░░░    ├─ Artifact Upload    ██████████
├─ PR Comments       ░░░░░░░░░░    └─ PR Comments       ██████████
│
OVERALL: 4/10                      OVERALL: 8/10

ACTION: Copy artifacts/reporting from atoms-mcp-prod to atomsAgent
```

### 4️⃣ CODE QUALITY TOOLS

```
┌────────────────────────┬──────────────────┬──────────────────┐
│ Tool                   │ atomsAgent       │ atoms-mcp-prod   │
├────────────────────────┼──────────────────┼──────────────────┤
│ Linter                 │ ruff 0.8.0       │ ruff 0.8.4       │
│ Type Checker           │ mypy 1.14.0      │ mypy 1.13.0      │
│ Code Formatter         │ ⚠️ (ruff only)   │ ⚠️ (ruff only)   │
│ Security Checker       │ ✅ S* rules      │ ❌ Limited       │
│ Complexity Checker     │ ⚠️ Optional      │ ⚠️ Optional      │
│ Pre-commit Hooks       │ ? (verify)       │ ? (verify)       │
│ Documentation Linter   │ ❌ No            │ ✅ spellcheck    │
└────────────────────────┴──────────────────┴──────────────────┘

RECOMMENDATION: Align both to atomsAgent's explicit rule selection
                + atoms-mcp-prod's comprehensive mypy config
```

### 5️⃣ DEPENDENCY MANAGEMENT

```
Core Dependencies Health Check:

atomsAgent:
  ✅ All pinned with ranges
  ✅ Lock file (uv.lock)
  ⚠️ Many optional deps (27)
  ⚠️ Heavy dependency tree

atoms-mcp-prod:
  ✅ All pinned with ranges
  ✅ Lock file (uv.lock)
  ✅ Lean dependency tree (18 core)
  ✅ Well-organized optional groups

RECOMMENDATION: Keep both approaches, document in ADR
```

---

## Decision Tree: Adopt From Where?

```
Question: Should atomsAgent adopt this from atoms-mcp-prod?

fastmcp upgrade?
├─ YES → Upgrade to 2.13.1+
│        Risk: Medium | Effort: 1h | Priority: CRITICAL
│
Python version?
├─ YES → Pin to 3.12
│        Risk: Low | Effort: 1h | Priority: CRITICAL
│
Coverage CI?
├─ YES → Add 95% threshold
│        Risk: Low | Effort: 2h | Priority: CRITICAL
│
Enhanced test reporting?
├─ YES → Copy enhanced-testing.yml
│        Risk: Low | Effort: 2h | Priority: HIGH
│
Async mode (auto vs strict)?
├─ AUTO → More forgiving
│        Risk: Low | Effort: 0.5h | Priority: MEDIUM
│
Timeout config?
├─ YES → Add 300s with thread method
│        Risk: Low | Effort: 0.5h | Priority: MEDIUM
│
Pytest markers?
├─ MERGE → Combine both sets
│        Risk: Low | Effort: 1h | Priority: MEDIUM
│
Ruff config?
├─ HYBRID → atoms-agent's explicit + atoms-mcp-prod's rules
│         Risk: Low | Effort: 1h | Priority: MEDIUM
│
MyPy config?
├─ ENHANCE → Use atoms-mcp-prod's comprehensive config
│          Risk: Low | Effort: 1h | Priority: MEDIUM

Total Effort: ~10 hours | All Priority CRITICAL or HIGH
```

---

## Risk Heat Map

```
HIGH RISK ⚠️
├─ fastmcp upgrade (probability: Medium, impact: High)
│  Mitigation: Test in branch, run MCP tests
│
└─ Coverage introduction (probability: Medium, impact: Medium)
   Mitigation: Gradual threshold increase, work with teams

MEDIUM RISK 🟠
├─ Python version pin (probability: Low, impact: Medium)
│  Mitigation: Standard upgrade path
│
├─ Config changes (probability: Low, impact: Medium)
│  Mitigation: Review before merge, rollback plan
│
└─ Team adoption (probability: Low, impact: High)
   Mitigation: Clear docs, training, gradual rollout

LOW RISK ✅
├─ Test reporting enhancements (probability: Low, impact: Low)
├─ Script organization (probability: Low, impact: Low)
├─ Documentation (probability: Low, impact: Low)
└─ Marker consolidation (probability: Low, impact: Low)
```
