Skip to content

functional-scope.md

Latest commit

 

History

History
190 lines (153 loc) · 15.8 KB

functional-scope.md

File metadata and controls

190 lines (153 loc) · 15.8 KB

Evolith Tracker: System Functional Scope (SDLC Suite)

Bilingual Navigation: English (this document) · Versión en Español

Document Status: Draft (refactored 2026-06-11 — from per-module scope to system scope) Type: Functional Scope · Phase 1 artifact Satellite: Evolith Tracker · Upstream: Evolith Core

1. Overview

Evolith Tracker is the Governance Control Plane for AI-Native software engineering: a suite that digitizes, automates, and audits the full software lifecycle through 5 sequential Phase Gates, strictly enforcing the Evolith Core architectural rules. It is not a task manager and does not replace specialized tools: under the Governed Composition model, the Tracker builds the irreducible governance core (gates, traceability, Core rules, Evidence Graph) and consumes mature capabilities from external providers via Ports and Adapters.

The Core defines. Providers execute. Evaluators assess. Tracker decides and audits.

The Tracker is the single authority for phase transitions: no initiative advances without formally passing its gate (BR-001..BR-003), and every decision is audited, attributed, and immutable (BR-009).

2. Gates, Iteration, and Baselines

Refinement is iterative inside each phase: initiatives, backlogs, contracts, and stories are versioned and split freely while the phase is open. But passing a gate freezes that phase's baseline (scope freeze at Business Sign-Off; immutable contracts at Design Baseline). Any change after a passed gate re-enters through governance — an ExceptionRequest or the Re-Do Flow contingency engine — never through silent edits. There are no "living" artifacts after their gate: there is governed versioning.

3. The 5 Value-Stream Modules

Strict, non-negotiable core workflow of each module; each phase has its artifact set per the Evolith SDLC standard.

# Module Core workflow (non-negotiable) Exit gate
1 Discovery & Ideation Hub Initiative registration; business gate with PO justification (ROI, Time to Market) and technical justification (ballpark estimation); backlog generation or initiative-only tracking upon approval (per tenant config) Business Sign-Off — scope frozen
2 Architecture Spec-Driven OpenAPI/AsyncAPI contracts (REST is the sole API surface in Phase 1, T-009); Core-conformant ADRs; versioned Technical Blueprint Design Baseline approved
3 Construction Tracking Story↔contract traceability; evidence from external SCM/CI via ports; real-time Architecture Drift detection (BR-004) Successful build — merge authorized
4 Automated QA & Integration .harness results ingestion; contract and regression testing; quality verdict Quality Gate — CFR < 2%
5 Dynamic Release Planner Multi-environment calendar crossed with regression scores; Re-Do Flow on blockers; final human sign-off Production live — monitoring nominal

4. Cross-Cutting System Capabilities

  • Orchestration: the Tracker assigns work, validates deliverables against gate criteria, and audits every action. The agents that execute the work belong to the tenant-configured agent framework (bmad by default, spec-kit, custom, etc.). BMAD is orchestration only — agents cannot self-assign or skip gates.
  • Three equivalent surfaces: Web Application, CLI, and MCP Server with full feature parity (BR-008).
  • Parametrizable multi-tenancy: each tenant configures optional steps, approval levels, execution mode (manual/automated), backlog mode ("generate" or "initiative-only"), and agent framework (bmad by default, spec-kit, custom, etc.) per phase, always honoring the non-negotiable core workflow; absolute data isolation per TenantID (BR-006).
  • Standalone use and interoperability: every module can operate decoupled. For import, any external task can be integrated and associated with the Evolith Tracker initiative as its entry point. For export, results can be sent to any external system that needs to analyze them (Jira, Trello, CSV, APIs, etc.), all channeled through the Integration ACL.
  • Analytical brain: immutable Evidence Graph; DORA and SPACE metrics; Architecture Adherence Index with early drift alerts.
  • Delegated identity: AuthN/AuthZ and RACI roles consumed from the UMS SaaS — the Tracker manages no users.
  • Inherited governance: Evolith Core rules are immutable at Tracker level (BR-005); improvements are proposed upstream via evidence-backed ADRs.

5. Out of Scope

  • Custom per-tenant methodologies (the Tracker enforces the Evolith SDLC). Per-tenant agent framework selection does not constitute a custom methodology: the core workflow, gates, and standard artifacts remain invariant.
  • User management, authentication, or identity (delegated to UMS).
  • Code execution or IDE integration (the MCP Server covers agent integration).
  • Billing and subscription management.
  • GraphQL as an API surface (T-009) and distributed-service extraction — both Phase 2.

6. Artifact Catalog

Phase 1: Discovery (Gate 1) — Required

Artifact Format Author Phase Core Schema / Template
PRD — Product Requirements Document Markdown Product Owner / PM 1 prd.schema.json
Discovery Canvas JSON/Markdown Requester / PM 1 discovery-canvas.schema.json
Business Case (ROI) JSON/YAML Product Owner 1 business-case-roi.schema.json
Ballpark Estimation JSON/Excel Architect / Tech Lead 1 ballpark-estimation.schema.json
Evolith User Story Markdown/JSON AI Agent / PM 1 evolith-user-story.schema.json
Agile Backlog JSON/CSV Product Owner 1 agile-backlog.schema.json
CLI Impact Analysis Markdown Architect 1 cli-impact-analysis.schema.json
Architectural Directives Markdown Architect 1 [Template pending]
Repository Taxonomy Markdown Architect 1 [Template pending]
Agnostic Baseline (Tech Stack) Markdown Architect 1 [Template pending]
ADR-0047 — Modular Monolith Selection Markdown Architect 1 [Template pending]
Engineering Manifesto Markdown Engineering Lead 1 [Template pending]
MoSCoW Prioritization Matrix JSON/Markdown Product Owner 1 [Template pending]

Phase 1: Discovery (Gate 1) — Optional

Artifact Format Author Phase Core Schema / Template
Evolutionary Strategy Roadmap Markdown Product Owner 1 [Template pending]
Maturity Assessment JSON/Markdown Architect 1 [Template pending]
Architecture Communication Strategy Markdown Architect 1 [Template pending]
UMS Reference Model JSON/Markdown Architect 1 [Template pending]

Phase 2: Design (Gate 2) — Required

Artifact Format Author Phase Core Schema / Template
API/Event Contracts YAML/JSON (OpenAPI/AsyncAPI) Architect / AI Agent 2 [Schema pending — GAP-020]
ADR (Decision Record) Markdown Architect 2 adr.schema.json
Data Schema Definition SQL/DDL Data Architect 2 [Schema pending — GAP-020]
Technical Blueprint JSON/ZIP Lead Architect 2 [Schema pending — GAP-020]
Reference Blueprint Markdown Architect 2 [Template pending]
Authoritative Tech Stack Markdown Architect 2 [Template pending]
ADR Decision Matrix JSON/Markdown Architect 2 [Template pending]
ADR-0002 — Hexagonal Architecture Markdown Architect 2 [Template pending]
ADR-0018 — Testing Pyramid Markdown Architect 2 [Template pending]
ADR-0031 — Schema-per-Context Markdown Architect 2 [Template pending]
ADR-0032 — Protocol Selection Matrix Markdown Architect 2 [Template pending]
ADR-0056 — Naming and Design Conventions Markdown Architect 2 [Template pending]
Functional Story Markdown/JSON Product Owner / AI Agent 2 functional-story.schema.json
Functional Story Writing Standard Markdown Architect 2 [Template pending]
SDLC Documentation Best Practices Markdown Architect 2 [Template pending]
Simplicity Checklist (Phase 1) Markdown Architect 2 [Template pending]
Bounded Context Map (C4) Diagram/PNG Architect 2 [Template pending]

Phase 2: Design (Gate 2) — Optional

Artifact Format Author Phase Core Schema / Template
ADR-0010 — Multi-Tenancy Markdown Architect 2 [Template pending]
ADR-0045 — Extraction Readiness Criteria Markdown Architect 2 [Template pending]
C4 Topology Spec Diagram/PNG Architect 2 [Template pending]
CAP Strategic Analysis Markdown Architect 2 [Template pending]
Observability Architecture Flow Markdown Architect 2 [Template pending]
Canonical Patterns Markdown Architect 2 [Template pending]

Phase 3: Construction (Gate 3) — Required

Artifact Format Author Phase Core Schema / Template
Technical Story Markdown/JSON SM / Dev 3 technical-story.schema.json
Drift Report JSON/Markdown BMAD Agent 3 [Schema pending — GAP-020]
Code Coverage Report JSON/HTML CI Pipeline 3 [Schema pending — GAP-020]
Peer Review Summary JSON/Markdown Dev / SM 3 [Schema pending — GAP-020]
Definition of Done Checklist Markdown/JSON SM / Dev 3 [Schema pending — GAP-020]
Documentation Delta (PR-driven) Markdown/JSON Dev 3 [Schema pending — GAP-020]
Engineering Manifesto Markdown Engineering Lead 3 [Template pending]
SDLC Framework (Construction SS3-4) Markdown Engineering Lead 3 [Template pending]
SDLC Quality Gates JSON/Markdown QA / Engineering Lead 3 [Template pending]
ADR-0005 — CI/CD Pipeline Markdown DevOps 3 [Template pending]
ADR-0018 — Testing Pyramid Markdown Architect 3 [Template pending]
ADR-0049 — Naming Semantics and Clean Code Markdown Architect 3 [Template pending]
ADR-0050 — GitFlow Branching Strategy Markdown DevOps 3 [Template pending]
SDLC Documentation Best Practices Markdown Architect 3 [Template pending]
Canonical Patterns Markdown Architect 3 [Template pending]
CI Pipeline Evidence JSON (external) CI Pipeline 3 [Schema pending — GAP-020]
Coverage Report (external) JSON/HTML CI Pipeline 3 [Schema pending — GAP-020]

Phase 4: QA (Gate 4) — Required

Artifact Format Author Phase Core Schema / Template
Test Summary Report Markdown/JSON QA 4 test-summary-report.schema.json
SDLC Quality Gates JSON/Markdown QA / Engineering 4 [Schema pending — GAP-020]
ADR-0018 — Testing Pyramid Markdown Architect 4 [Template pending]
ADR-0052 — Unit Testing Isolation Strategy Markdown QA / Dev 4 [Schema pending — GAP-020]
ADR-0053 — Integration/E2E Testing Strategy Markdown QA / Dev 4 [Schema pending — GAP-020]
Acceptance Validation (PO Sign-off) JSON/Markdown Product Owner 4 [Schema pending — GAP-020]
Security Scan Report JSON/HTML CI Pipeline 4 [Schema pending — GAP-020]
Pyramid Distribution Evidence JSON CI Pipeline 4 [Schema pending — GAP-020]

Phase 4: QA (Gate 4) — Optional

Artifact Format Author Phase Core Schema / Template
Contract Testing Guideline Markdown QA / Dev 4 [Schema pending — GAP-020]
ADR-0037 — Performance/Chaos Verification Markdown QA 4 [Template pending]
Vendor Risk Assessment JSON/Markdown Security 4 [Schema pending — GAP-020]
Observability Architecture Flow Markdown Architect 4 [Template pending]

Phase 5: Release (Gate 5) — Required

Artifact Format Author Phase Core Schema / Template
Release Notes Markdown Release Manager 5 release-notes.schema.json
Rollback Procedure Markdown DevOps / Release 5 [Schema pending — GAP-020]
Deployment Evidence JSON (external) CD Pipeline 5 [Schema pending — GAP-020]
ADR-0007 — OTel and Loki Observability Markdown DevOps 5 [Template pending]
ADR-0013 — Cloud Topology and DR Markdown DevOps 5 [Template pending]
ADR-0005 — CI/CD Pipeline Markdown DevOps 5 [Template pending]
Operations Hub Markdown DevOps 5 [Template pending]
Infrastructure Hub Markdown DevOps 5 [Template pending]
SDLC Documentation Best Practices Markdown Architect 5 [Template pending]
Observability Validation JSON Monitoring 5 [Schema pending — GAP-020]

Cross-cutting — Always Required

Artifact Format Author Phase Core Schema / Template
Agnostic Baseline (Tech Stack) Markdown Architect All [Template pending]
Reference Architecture Blueprint Markdown Architect All [Template pending]
Engineering Manifesto Markdown Engineering Lead All [Template pending]
Definition of Done (SDLC Framework) Markdown Engineering Lead All [Template pending]
Repository Taxonomy Markdown Architect All [Template pending]
Gate Evidence JSON BMAD / System All gate-evidence.schema.json

(Exact schemas and template URLs must be published from Evolith Core — see UPSTREAM_PROPOSALS Proposal 3, GAP-020).

7. Architecture Integration (Phase 1)

  • Frontend: Shell Host (Module Federation, T-002) + one React remote microfrontend per module, with a mobile PWA build.
  • Backend: Progressive Monolith with one Bounded Context per module; no service extraction in Phase 1.
  • Data: one PostgreSQL schema per context under the tracker_<context> convention (T-008); UUID references between schemas, no cross-schema FKs.
  • Event Bus: phases advance through domain events via the transactional outbox (InitiativeApprovedEvent → DesignApprovedEvent → ConstructionGatePassedEvent → QualityGatePassedEvent).