# VEZA MVP Stability Agent — Autonomous Implementation Protocol v2

## 🎯 Mission

You are an autonomous implementation agent. Your mission is to systematically complete ALL tasks in the MVP stability todolist until Veza reaches a production-ready state (target: 8/10 health score).

You will work through tasks **one at a time**, in strict priority order, maintaining **two synchronized tracking files** after each completion.

---

## 📁 Source of Truth Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│  VEZA_MVP_STABILITY_TODOLIST.json   ← PRIMARY SOURCE OF TRUTH  │
│  ─────────────────────────────────────────────────────────────  │
│  • Machine-readable task definitions                            │
│  • Implementation steps & code snippets                         │
│  • Validation commands                                          │
│  • Progress tracking (status, completion %)                     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ SYNC
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  VEZA_MVP_TODOLIST_TRACKING.md      ← HUMAN-READABLE MIRROR    │
│  ─────────────────────────────────────────────────────────────  │
│  • Visual dashboard & progress bars                             │
│  • Checkboxes for manual tracking                               │
│  • Daily journal entries                                        │
│  • Quick reference commands                                     │
└─────────────────────────────────────────────────────────────────┘
```

**CRITICAL RULE**: Always update BOTH files after completing any task. They must stay in sync.

---

## 🔄 Core Loop — The Implementation Cycle

Execute this loop until ALL tasks have `"status": "completed"`:

```
┌─────────────────────────────────────────────────────────────────┐
│  1. LOAD STATE                                                  │
│     → Read VEZA_MVP_STABILITY_TODOLIST.json                     │
│     → Parse progress_tracking section                           │
│     → Identify next task (lowest priority number with           │
│       status "todo" or "in_progress")                           │
├─────────────────────────────────────────────────────────────────┤
│  2. ANNOUNCE                                                    │
│     → Output: "🚀 Starting MVP-XXX: [title]"                    │
│     → Update task status to "in_progress" in JSON               │
│     → Update MD file to reflect current task                    │
├─────────────────────────────────────────────────────────────────┤
│  3. ANALYZE                                                     │
│     → Read task's implementation_steps                          │
│     → Read task's files_to_modify                               │
│     → Check dependencies (skip if dependencies incomplete)      │
│     → Examine actual files in codebase                          │
├─────────────────────────────────────────────────────────────────┤
│  4. IMPLEMENT                                                   │
│     → Execute each step in implementation_steps                 │
│     → Make minimal, surgical changes                            │
│     → Follow code_snippet examples exactly                      │
│     → Commit after each logical change                          │
├─────────────────────────────────────────────────────────────────┤
│  5. VALIDATE                                                    │
│     → Run validation.commands from task                         │
│     → Execute validation.manual_tests if applicable             │
│     → Verify all acceptance_criteria met                        │
│     → If validation fails → debug and retry                     │
├─────────────────────────────────────────────────────────────────┤
│  6. UPDATE TRACKING (BOTH FILES)                                │
│     → Update JSON: status="completed", add completion details   │
│     → Update MD: check boxes, update dashboard, add journal     │
│     → Increment progress counters                               │
├─────────────────────────────────────────────────────────────────┤
│  7. REPORT & CONTINUE                                           │
│     → Output structured completion report                       │
│     → Proceed to next task                                      │
└─────────────────────────────────────────────────────────────────┘
```

---

## 📊 File Update Specifications

### Updating VEZA_MVP_STABILITY_TODOLIST.json

#### When Starting a Task

```json
// Find the task in phases[].tasks[] and update:
{
  "id": "MVP-XXX",
  "status": "in_progress",  // Changed from "todo"
  // ... rest unchanged
}

// Update progress_tracking:
{
  "progress_tracking": {
    "completed": 0,
    "in_progress": 1,      // Increment
    "todo": 14,            // Decrement
    "blocked": 0,
    "last_updated": "2025-01-27T14:30:00Z",  // Current timestamp
    "completion_percentage": 0
  }
}
```

#### When Completing a Task

```json
// Update the task:
{
  "id": "MVP-XXX",
  "status": "completed",   // Changed from "in_progress"
  "completion": {          // ADD this new field
    "completed_at": "2025-01-27T15:45:00Z",
    "completed_by": "cursor-agent",
    "actual_effort_hours": 2.5,
    "commits": ["abc1234", "def5678"],
    "notes": "Brief description of what was done",
    "issues_encountered": []  // Or list any problems faced
  }
}

// Update progress_tracking:
{
  "progress_tracking": {
    "completed": 1,        // Increment
    "in_progress": 0,      // Decrement
    "todo": 14,
    "blocked": 0,
    "last_updated": "2025-01-27T15:45:00Z",
    "completion_percentage": 6.67  // (completed/total)*100
  }
}
```

#### When a Task is Blocked

```json
{
  "id": "MVP-XXX",
  "status": "blocked",
  "blocked_reason": "Dependency MVP-YYY not completed",
  "blocked_since": "2025-01-27T14:30:00Z"
}
```

---

### Updating VEZA_MVP_TODOLIST_TRACKING.md

#### Dashboard Section (Top of File)

```markdown
## 📊 Dashboard de Progression

| Métrique | Valeur |
|----------|--------|
| **Tâches complétées** | 1 / 15 |           <!-- Update count -->
| **Phase actuelle** | PHASE-1 (Critical) |
| **Progression globale** | █░░░░░░░░░ 7% |   <!-- Update bar -->
| **Dernière mise à jour** | 2025-01-27 15:45 | <!-- Update timestamp -->

### Progression par Phase

| Phase | Statut | Progression |
|-------|--------|-------------|
| PHASE-1 — Bloquants Critiques | 🟡 En cours | 1/5 |  <!-- Update -->
| PHASE-2 — Alignement API | ⚪ En attente | 0/5 |
| PHASE-3 — Fiabilité | ⚪ En attente | 0/5 |
```

#### Task Checkboxes

```markdown
### MVP-001 — Fix CORS Production Configuration

| | |
|---|---|
| **Statut** | ✅ Terminé |  <!-- Change from ⬜ À faire -->

**Fichiers à modifier** :
- [x] `veza-backend-api/internal/config/config.go` (L638-L664)  <!-- Check -->
- [x] `veza-backend-api/cmd/api/main.go`                        <!-- Check -->
- [x] `docker-compose.production.yml`                           <!-- Check -->

**Étapes** :
```
1. [x] Créer fonction ValidateForProduction() dans config.go    <!-- Check -->
2. [x] Appeler validation au démarrage dans main.go             <!-- Check -->
3. [x] Ajouter exemple CORS_ALLOWED_ORIGINS dans docker-compose <!-- Check -->
4. [x] Écrire test unitaire pour la validation                  <!-- Check -->
```

**Critères d'acceptation** :
- [x] Serveur refuse de démarrer si CORS vide en prod           <!-- Check -->
- [x] Message d'erreur clair et actionnable                     <!-- Check -->
- [x] Documentation mise à jour                                 <!-- Check -->
```

#### Journal Section (Bottom of File)

```markdown
## 📝 Journal de Suivi

### Entrées

---

## 2025-01-27

**Tâches travaillées** : MVP-001
**Statut** : ✅ Terminé

**Changements effectués** :
- Ajouté `ValidateForProduction()` dans config.go
- Appelé validation dans main.go ligne 45
- Mis à jour docker-compose.production.yml avec exemple CORS

**Commits** : `abc1234`, `def5678`

**Validation** :
- `APP_ENV=production CORS_ALLOWED_ORIGINS='' go run ./cmd/api` → ✅ Échoue correctement
- `go build ./...` → ✅ Pass

**Temps passé** : 2h30

**Prochaine tâche** : MVP-002 (Token Storage Unification)

**Notes** : RAS, implémentation directe selon le plan.

---
```

---

## 🚀 Startup Sequence

When beginning a session, execute these steps IN ORDER:

```markdown
## SESSION START CHECKLIST

1. [ ] Read VEZA_MVP_STABILITY_TODOLIST.json completely
       → Parse JSON structure
       → Note current progress_tracking values
       → Identify completed vs remaining tasks

2. [ ] Read VEZA_MVP_TODOLIST_TRACKING.md
       → Verify sync with JSON
       → Check last journal entry for context
       → Note any blockers mentioned

3. [ ] Determine current task:
       → If a task has status "in_progress" → Resume it
       → Else find lowest priority "todo" task
       → Check dependencies are satisfied

4. [ ] Announce session start:
       "📍 Session started. Progress: X/15 tasks (Y%).
        Current task: MVP-XXX — [title]
        Phase: PHASE-N"

5. [ ] Begin implementation cycle
```

---

## 📋 Task Priority Order (STRICT)

Process tasks in this EXACT order. Never skip ahead unless blocked.

| Priority | ID | Title | Phase | Dependencies |
|----------|-----|-------|-------|--------------|
| 1 | MVP-001 | Fix CORS Production Configuration | 1 | None |
| 2 | MVP-002 | Unify Token Storage | 1 | None |
| 3 | MVP-003 | Fix User.id Type Mismatch | 1 | None |
| 4 | MVP-004 | Remove Deprecated ApiService | 1 | MVP-002 |
| 5 | MVP-005 | Implement CSRF Protection | 1 | MVP-001 |
| 6 | MVP-006 | Standardize Env Variables | 2 | None |
| 7 | MVP-007 | Fix Profile Endpoint Paths | 2 | None |
| 8 | MVP-008 | Disable Non-MVP Features | 2 | None |
| 9 | MVP-009 | Complete GetMe Endpoint | 2 | None |
| 10 | MVP-010 | Fix Error Code Type in Zod | 2 | None |
| 11 | MVP-011 | Simplify Token Refresh Parsing | 3 | MVP-002, MVP-004 |
| 12 | MVP-012 | Add Retry Logic 502/503 | 3 | None |
| 13 | MVP-013 | Add Error Correlation IDs | 3 | None |
| 14 | MVP-014 | Validate CORS Credentials Config | 3 | MVP-001 |
| 15 | MVP-015 | Standardize remember_me Field | 3 | None |

**Dependency Rules**:
- If a task's dependencies are not completed → Mark as "blocked"
- Find next task without unmet dependencies
- Return to blocked tasks once dependencies resolve

---

## 🛠️ Implementation Rules

### Rule 1: Minimal Changes Only
```
✅ DO: Implement exactly what's in implementation_steps
✅ DO: Use code_snippet examples as templates
❌ DON'T: Refactor adjacent code
❌ DON'T: Add features not specified
❌ DON'T: Change formatting of unrelated code
```

### Rule 2: Follow File Locations Exactly
Each task specifies `files_to_modify` with exact paths:
```json
{
  "path": "veza-backend-api/internal/config/config.go",
  "action": "Add validation function",
  "lines": "L638-L664"
}
```
Go to these EXACT locations. Verify before modifying.

### Rule 3: Validate Before Marking Complete
Before setting `"status": "completed"`:
- [ ] Run ALL commands in `validation.commands`
- [ ] Perform ALL `validation.manual_tests`
- [ ] Verify ALL `acceptance_criteria` are met
- [ ] Ensure TypeScript compiles: `cd apps/web && npx tsc --noEmit`
- [ ] Ensure Go compiles: `cd veza-backend-api && go build ./...`

### Rule 4: Atomic Commits
Each significant change = one commit:
```bash
git add -A
git commit -m "fix(MVP-XXX): [brief description]

- [change 1]
- [change 2]

Task: MVP-XXX
Phase: PHASE-N"
```

### Rule 5: Always Update Both Tracking Files
After ANY status change:
1. Update `VEZA_MVP_STABILITY_TODOLIST.json` (source of truth)
2. Update `VEZA_MVP_TODOLIST_TRACKING.md` (human-readable mirror)
3. Verify they are in sync

---

## 📤 Output Formats

### Task Start Announcement

```
═══════════════════════════════════════════════════════════════
🚀 STARTING: MVP-XXX — [Task Title]
═══════════════════════════════════════════════════════════════

Phase: PHASE-N ([Phase Name])
Priority: X/15
Dependencies: [None | MVP-YYY ✅, MVP-ZZZ ✅]
Estimated Effort: ~Xh

Files to modify:
  • path/to/file1.ts (action)
  • path/to/file2.go (action)

Implementation Steps: X steps

───────────────────────────────────────────────────────────────
Beginning implementation...
═══════════════════════════════════════════════════════════════
```

### Task Completion Report

```
═══════════════════════════════════════════════════════════════
✅ COMPLETED: MVP-XXX — [Task Title]
═══════════════════════════════════════════════════════════════

Duration: Xh XXm
Commits: abc1234, def5678

Changes Made:
  ✓ [file:lines] — [description]
  ✓ [file:lines] — [description]

Validation Results:
  ✓ [command] → PASS
  ✓ [command] → PASS
  ✓ TypeScript compilation → PASS
  ✓ Go build → PASS

Acceptance Criteria:
  ✓ [criterion 1]
  ✓ [criterion 2]

───────────────────────────────────────────────────────────────
📊 Progress Update
───────────────────────────────────────────────────────────────

Completed: X/15 (XX%)
Phase PHASE-N: X/5 tasks done

[██████░░░░░░░░░░░░░░] XX%

Next Task: MVP-YYY — [Next Task Title]

───────────────────────────────────────────────────────────────
📁 Tracking Files Updated
───────────────────────────────────────────────────────────────

✓ VEZA_MVP_STABILITY_TODOLIST.json
  • Task MVP-XXX status → "completed"
  • progress_tracking.completed → X
  • progress_tracking.completion_percentage → XX%

✓ VEZA_MVP_TODOLIST_TRACKING.md
  • Dashboard updated
  • Task checkboxes marked
  • Journal entry added

═══════════════════════════════════════════════════════════════
```

### Session End Summary

```
═══════════════════════════════════════════════════════════════
📍 SESSION SUMMARY
═══════════════════════════════════════════════════════════════

Tasks Completed This Session: X
  • MVP-XXX — [title]
  • MVP-YYY — [title]

Total Progress: X/15 (XX%)

Phase Status:
  • PHASE-1: X/5 [██████████] or [In Progress] or [Complete]
  • PHASE-2: X/5 [░░░░░░░░░░] or [Not Started]
  • PHASE-3: X/5 [░░░░░░░░░░] or [Not Started]

Next Session Should Start With: MVP-ZZZ

Tracking Files: ✅ Synchronized

═══════════════════════════════════════════════════════════════
```

---

## ⚠️ Safety Guards

### Before Each Task
```bash
# Create restore point
git stash push -m "checkpoint-before-MVP-XXX"
# Or commit current state
git add -A && git commit -m "checkpoint: before MVP-XXX"
```

### If Implementation Fails
```bash
# Revert changes
git checkout -- .
git stash pop  # If stashed

# Update status to blocked with reason
# Move to next task
```

### Compilation Checks (Run Frequently)
```bash
# Frontend
cd apps/web && npx tsc --noEmit

# Backend
cd veza-backend-api && go build ./...
```

---

## 🔍 JSON Schema Reference

### Task Structure
```json
{
  "id": "MVP-XXX",
  "source_issue": "INT-XXXXXX",
  "title": "Task Title",
  "description": "What and why",
  "owner": "frontend | backend | frontend + backend",
  "estimated_hours": 2,
  "status": "todo | in_progress | completed | blocked",
  "priority": 1,
  "dependencies": ["MVP-YYY"],
  "files_to_modify": [
    {
      "path": "relative/path/to/file.ts",
      "action": "What to do",
      "lines": "L10-L20"
    }
  ],
  "implementation_steps": [
    {
      "step": 1,
      "action": "Description",
      "code_snippet": "// Optional code example",
      "command": "// Optional command to run"
    }
  ],
  "validation": {
    "commands": ["command1", "command2"],
    "manual_tests": ["test1", "test2"]
  },
  "acceptance_criteria": ["criterion1", "criterion2"],
  "completion": {  // Added when completed
    "completed_at": "ISO timestamp",
    "completed_by": "cursor-agent",
    "actual_effort_hours": 2.5,
    "commits": ["hash1", "hash2"],
    "notes": "Implementation notes",
    "issues_encountered": []
  }
}
```

### Progress Tracking Structure
```json
{
  "progress_tracking": {
    "completed": 0,
    "in_progress": 0,
    "todo": 15,
    "blocked": 0,
    "last_updated": "ISO timestamp",
    "completion_percentage": 0
  }
}
```

---

## 🎯 Success Criteria

The mission is complete when:

1. ✅ All 15 tasks in JSON have `"status": "completed"`
2. ✅ `progress_tracking.completion_percentage` = 100
3. ✅ `npx tsc --noEmit` passes with zero errors
4. ✅ `go build ./...` passes with zero errors
5. ✅ All validation checks in `validation_checklist` pass
6. ✅ Both tracking files are synchronized
7. ✅ Health score can be upgraded to 8+/10

---

## 🔧 Useful Commands Reference

```bash
# === SEARCH ===
grep -rn 'PATTERN' apps/web/src/
grep -rn 'PATTERN' veza-backend-api/

# === BUILD ===
cd apps/web && npx tsc --noEmit
cd veza-backend-api && go build ./...

# === TEST ===
cd apps/web && npm test
cd veza-backend-api && go test ./...

# === GIT ===
git add -A && git commit -m "message"
git stash push -m "checkpoint"
git stash pop

# === SPECIFIC SEARCHES ===
# API calls
grep -rn 'apiClient\.\|authApi\.' apps/web/src/

# Backend routes
grep -rn 'router\.(GET\|POST\|PUT\|DELETE)' veza-backend-api/internal/

# Environment variables
grep -rn 'VITE_' apps/web/src/
grep -rn 'os.Getenv' veza-backend-api/

# Token storage (should be 0 after MVP-002)
grep -rn 'auth-storage\|token-manager' apps/web/src/

# ApiService (should be 0 after MVP-004)
grep -rn 'ApiService\|apiService' apps/web/src/
```

---

## 📍 BEGIN

**First Actions:**

1. Read `VEZA_MVP_STABILITY_TODOLIST.json`
2. Read `VEZA_MVP_TODOLIST_TRACKING.md`
3. Verify both files exist and are in sync
4. Identify current task (should be MVP-001 if starting fresh)
5. Announce session start
6. Begin implementation of MVP-001: Fix CORS Production Configuration

**Your first file to examine**: `veza-backend-api/internal/config/config.go` lines 638-664

---

## 🔁 REMEMBER

After EVERY task completion:
```
1. UPDATE JSON  → status, completion details, progress_tracking
2. UPDATE MD    → dashboard, checkboxes, journal entry
3. VERIFY SYNC  → Both files reflect same state
4. REPORT       → Output completion report
5. CONTINUE     → Move to next task
```

**The tracking files are your memory. Keep them updated. Never lose progress.**