Skip to content

ROADMAP_V2_ACTUAL.md

Latest commit

 

History

History
424 lines (308 loc) · 11.5 KB

ROADMAP_V2_ACTUAL.md

File metadata and controls

424 lines (308 loc) · 11.5 KB
Raw

⚠️ [ARCHIVED - SEE ONE_TRUTH_MVP.md]

This document is outdated. Refer to ONE_TRUTH_MVP.md for current MVP roadmap.

🛡️ CERBER CORE V2.0 - ACTUAL ROADMAP (REALITY-BASED)

"Co JUŻ JEST, co BRAKUJE, ile GODZIN zostało"

Data: January 12, 2026
Audytowane przez: 15+ Years Production Engineering
Status: 60% V2.0 ROADMAP ZROBIONE, 40h zostało do release

⚡ QUICK STATUS

Komponent Status % Godzin Zrobione Godzin Zostało Uwagi
Orchestrator ✅ WDROŻONY 85% 50h 5h 545 linii, SOLID, DIP
Profiles (solo/dev/team) ✅ WDROŻONY 90% 35h 3h 273 linii, hierarchy OK
Contract + Schemas ✅ WDROŻONY 80% 25h 5h Walidacja, extend, merge
Tool Detection ✅ WDROŻONY 75% 15h 5h Instalacja, version check
Adapters (actionlint, zizmor, gitleaks) ✅ WDROŻONY 70% 30h 10h Parser, output normalizacja
Reporting (text, json, github) ✅ WDROŻONY 75% 18h 6h Brak SARIF
File Discovery ✅ WDROŻONY 80% 12h 3h Git, staged, changed, all
Circuit Breaker + Retry ✅ WDROŻONY 85% 28h 5h TTL cleanup, strategies
State Machine ⚠️ CZĘŚCIOWO 40% 8h 12h ExecutionContext exist, integration incomplete
Observability Stack ⚠️ CZĘŚCIOWO 50% 10h 10h Logger, metrics, tracing - brak pełnej integracji
Guardian CLI ⚠️ CZĘŚCIOWO 30% 8h 8h Init OK, doctor stub, < 2s nie osiągnięty
CLI validate ✅ WDROŻONY 80% 12h 3h Flags OK, format support
Tests ✅ WDROŻONY 97% 100h 5h 1105/1140 passing (4 flaky git tests)
Execution Persistence ❌ BRAK 0% 0h 8h History, replay, audit trail - odłożone V2.1
Auto-Install ❌ BRAK 0% 0h 8h Download, cache, checksum - odłożone V2.1
Plugin System ❌ BRAK 0% 0h 6h Custom adapters - odłożone V2.1
SARIF Format ❌ BRAK 0% 0h 4h GitHub Code Scanning - V2.1
Docs (AGENTS.md, Architecture) ⚠️ CZĘŚCIOWO 60% 12h 8h Są, ale scattered
TOTAL 60% 410h 110h

Wniosek: ~40h zostało do MVP Release (Orchestrator + Profiles + Reliability)

📁 CO JUŻ ISTNIEJE W KODZIE

✅ Zrobione (nie duplikować w roadmapie!)

src/core/Orchestrator.ts (545 linii)

  • Strategy Pattern implementacja (DIP compliant)
  • Register + getAdapter + cache
  • Adapter execution (parallel/sequential)
  • Deterministic output + sorting
  • Error handling

src/core/ProfileResolver.ts (273 linii)

  • solo/dev/team hierarchy
  • Priority: CLI > env > default
  • Tools + failOn resolution
  • requireDeterministicOutput flag

src/core/circuit-breaker.ts + registry (300+ linii)

  • State machine (CLOSED, OPEN, HALF_OPEN)
  • Failure tracking + TTL
  • Stats tracking
  • Memory leak prevention

src/core/retry.ts + strategies (250+ linii)

  • Exponential backoff
  • Max retries
  • Optional circuit breaker integration

src/core/resilience/ (400+ linii)

  • ResilienceCoordinator (composition pattern)
  • AdapterExecutor (timeout wrapping)
  • ResultConverter (format normalization)
  • StatsComputer (aggregation)

src/core/strategies/ (300+ linii)

  • AdapterExecutionStrategy (interface)
  • LegacyExecutionStrategy (original logic)
  • ResilientExecutionStrategy (circuit breaker + retry)

src/adapters/ActionlintAdapter.ts (236 linii)

  • NDJSON + JSON array + text parsing
  • 3 output format support
  • Violation normalization

src/adapters/ZizmorAdapter.ts + GitleaksAdapter.ts

  • Security findings parsing
  • Severity mapping
  • Tool-specific output handling

src/contract/ (500+ linii)

  • ContractLoader (YAML parsing)
  • ContractValidator (schema validation)
  • Inheritance (extends: nodejs-base)
  • Profile resolution

src/reporting/ (400+ linii)

  • formatText() - human readable
  • formatJSON() - deterministic
  • formatGitHub() - ::error annotations
  • Violation merging + sorting

src/scm/git.ts

  • getStagedFiles() - pre-commit
  • getChangedFiles() - PR mode
  • getTrackedFiles() - all mode

src/cli/ (300+ linii)

  • init.ts - template generation
  • doctor.ts - stub (needs completion)
  • validate.ts - core command
  • override-validator.ts - profile override

test/ (1108+ passing tests)

  • 58 test suites passing
  • commit1-9 tests (each commit verified)
  • Snapshots (11 passing)
  • Integration tests
  • Only 4 flaky git tests (timeout on CI)

❌ CO BRAKUJE (ROADMAP ITEMS)

🔴 PRIORITY 1: MUST DO (dla MVP release)

1. State Machine Integration (8-10h)

Problem: ExecutionContext istnieje, ale Orchestrator go nie używa

  • ExecutionContext.ts napisany (interface + manager)
  • ExecutionState enum zdefiniowany
  • Ale: Orchestrator.run() nie emituje state transitions

Co zrobić:

// Orchestrator.run() powinno:
const context = this.contextManager.create(options);
await this.transitionTo(ExecutionState.VALIDATING_INPUT);
await this.validateInput(options);
// ... dla każdej fazy

Effort: 3-4h integration + 4-6h testing

2. Complete Guardian CLI < 2s (6-8h)

Problem: doctor.ts jest stub, Guardian profile (dev-fast) undefined

Co zrobić:

  1. Zaimplementuj cerber doctor:
    • Detect project type (package.json, Dockerfile)
    • Scan workflows (.github/workflows/)
    • Check tool installation (actionlint, zizmor)
    • Show health report
  2. Definiuj dev-fast profile (only actionlint, no zizmor)
  3. Benchmark: < 2s na pre-commit

Effort: 2-3h implementation + 3-4h testing

3. Guardian Integration with lint-staged (2-3h)

Co zrobić:

{
  "lint-staged": {
    ".github/workflows/*.yml": [
      "cerber validate --profile dev-fast --staged"
    ]
  }
}

Effort: 1-2h setup + 1h testing

4. Fix 4 Flaky Git Tests (2-3h)

Problem: FileDiscovery integration tests timeout na detached HEAD

  • filediscovery-real-git.test.ts: 4 timeouts

Co zrobić:

  1. Increase timeout (15s -> 30s)
  2. Mock git operations instead of real exec
  3. Skip long-running tests in CI

Effort: 2-3h

5. Verify No Regressions (2-3h)

Co zrobić:

  1. Run full test suite (npm test)
  2. Verify 1105+ passing
  3. Check CI green (GitHub Actions)

Effort: 1h execution + 1-2h debugging if needed

🟡 PRIORITY 2: NICE TO HAVE (dla pełnego V2.0)

6. Auto-Install Tooli (8-10h) - DEFER TO V2.1

Reason: Complexity > value dla MVP, defer to V2.1

Features:

  • Download binaries (not brew)
  • Cache ~/.cerber/tools/
  • Checksum verification
  • Lock mechanism (concurrent safety)
  • Version pinning

Effort: 8-10h full implementation + testing

7. SARIF Format (4-5h) - DEFER TO V2.1

Reason: GitHub Code Scanning is secondary, text + json + github enough for MVP

Features:

  • formatSARIF() function
  • GitHub Code Scanning integration
  • SARIF 2.1.0 schema compliance

Effort: 4-5h

8. Execution Persistence (8-10h) - DEFER TO V2.1

Reason: Nice for debugging, not critical for MVP

Features:

  • ExecutionStore (save to ~/.cerber/history/)
  • Replay capability
  • Audit trail
  • Secrets redaction

Effort: 8-10h

9. Complete Observability Stack (6-8h) - PARTIAL

Current state: Logger + metrics exist, not fully integrated

Co zrobić:

  1. Integration with Orchestrator phases
  2. Structured logging (JSON format)
  3. Metrics export (Prometheus-compatible)
  4. Tracing per adapter

Effort: 4-6h integration

📚 Documentation Gaps (4-6h)

10. AGENTS.md - AI Agent Rules

Status: Exists in ROADMAP, create standalone file Effort: 2-3h

11. ORCHESTRATOR_ARCHITECTURE.md

Status: Missing, need detailed architecture doc Effort: 2-3h

12. Update README with V2.0 Info

Status: Needs Orchestrator section, profiles explanation Effort: 1-2h

🚀 PRIORITIZED EXECUTION PLAN

WEEK 1: MVP Foundation (30h)

Day 1-2: Integration & Testing (10h)

  1. State machine integration (4h)
  2. Fix 4 flaky git tests (2h)
  3. Run full test suite (1h)
  4. Debugging + fixes (3h)

Day 3-4: Guardian CLI (10h)

  1. Implement cerber doctor (5h)
  2. dev-fast profile (2h)
  3. lint-staged integration (2h)
  4. Benchmark < 2s (1h)

Day 5: Quality Gate (10h)

  1. Full regression testing (3h)
  2. Documentation (4h)
  3. Code review + polish (3h)

Deliverable: MVP Release Ready (Orchestrator + Profiles + Reliability)

WEEK 2: Full V2.0 Polish (15h)

Day 6-7: Auto-Install (8h)

  1. Download mechanism (3h)
  2. Cache + checksum (3h)
  3. Tests (2h)

Day 8: SARIF + Observability (4h)

  1. SARIF format (2h)
  2. Observability integration (2h)

Day 9: Docs + Release (3h)

  1. Architecture documentation (2h)
  2. Release preparation (1h)

Deliverable: Full V2.0 Release

📊 EFFORT SUMMARY

Phase Hours What
Integration (State Machine) 8h Orchestrator state transitions
Guardian CLI 8h doctor, dev-fast, <2s
Testing + Fixes 8h Git tests, regression, quality gate
Auto-Install 8h Download, cache, checksum
SARIF + Observability 6h GitHub Code Scanning, structured logging
Documentation 6h AGENTS.md, architecture, README
Buffer 10h Unexpected issues, debugging
TOTAL 54h ~1.5 weeks @ 30h/week

MVP Release: 30h (1 week)
Full V2.0: 54h (1.5 weeks)

✅ DEFINITION OF DONE (MVP)

Technical:

  • State machine integrated (ExecutionContext in every phase)
  • cerber doctor working (tool detection, report generation)
  • cerber validate --profile dev-fast < 2s (pre-commit ready)
  • 1105+ tests passing (no regressions)
  • CI green (GitHub Actions)
  • All 3 adapters working (actionlint, zizmor, gitleaks)

Documentation:

  • README updated (Orchestrator, profiles, quick start)
  • AGENTS.md created
  • ORCHESTRATOR_ARCHITECTURE.md created
  • MIGRATION.md created (v1 → v2 guide)

Release:

  • package.json → 2.0.0
  • CHANGELOG updated
  • Git tag v2.0.0
  • NPM published

❌ NOT IN MVP (Defer to V2.1)

  • ❌ Auto-install (complexity, can use docs workaround)
  • ❌ Execution persistence (nice for debugging, not critical)
  • ❌ Plugin system (YAGNI for MVP)
  • ❌ Universal targets (GitLab CI, generic YAML - Phase 2.2)
  • ❌ SARIF format (GitHub Code Scanning secondary feature)

🎯 REALITY CHECK

Can We Release V2.0 in 2 Weeks? YES

Why:

  • 60% already implemented ✅
  • 1108/1140 tests passing ✅
  • Core features working ✅
  • Only 40h of integration left ✅

Risks:

  • ⚠️ Timeline tight
  • ⚠️ State machine integration untested
  • ⚠️ Guardian < 2s not verified
  • ⚠️ Git test flakiness

Mitigation:

  • Focus MVP only (defer nice-to-haves)
  • Daily standup + progress tracking
  • Parallel work where possible
  • Buffer time for debugging

Confidence: 8/10 (achievable, focused scope)

📝 NEXT IMMEDIATE ACTIONS (TODAY)

  1. ✅ Read this document (you're doing it!)
  2. ⏭️ Merge PR #56 (wait for CI)
  3. ⏭️ Create GitHub issue "State Machine Integration (8h)"
  4. ⏭️ Create GitHub issue "Guardian CLI Completion (8h)"
  5. ⏭️ Create GitHub issue "Fix Flaky Git Tests (3h)"
  6. ⏭️ Schedule standup (daily check-in)

ROADMAP STATUS: Reality-Based, Not Theoretical
LAST UPDATED: January 12, 2026, 15:30 UTC
AUDITOR: Senior Engineer (15+ Years)
NEXT REVIEW: January 13, 2026 (after State Machine integration)