# AI Agentic Roadmap and Phase Plan

## 1. Program Objective

Introduce agentic flow proposal capabilities while preserving existing production behavior for manual flow authoring and deterministic execution.

## 2. Guardrails

1. No runtime dispatch-path behavior changes in Phase 1
2. No AI auto-publish to production
3. Human approval remains mandatory before publish
4. Runtime execution must not depend on LLM-specific metadata

## 3. Phase Roadmap

## Phase 0: Alignment and Baseline (1-2 days)

Goal:
- Freeze scope, governance, and non-breaking constraints

Deliverables:
1. Approved architecture baseline
2. Approved technical contract baseline
3. Approval and RBAC decision matrix
4. Tenant policy baseline

Exit Gate:
- Stakeholder sign-off on architecture and technical spec

## Phase 1: Persistence and Lifecycle Foundation (2-3 days)

Goal:
- Enable proposal storage and state tracking

Deliverables:
1. Proposal and event persistence model
2. Lifecycle transition service
3. Event-audit capture for every transition
4. Unit tests for constraints and transitions

Exit Gate:
- Migrations and lifecycle tests pass in dev

## Phase 2: Internal APIs and Access Control (3-4 days)

Goal:
- Expose proposal lifecycle operations through secure endpoints

Deliverables:
1. Generate, get, approve, reject, open endpoints
2. Feature-flag guards
3. RBAC checks
4. API contract tests

Exit Gate:
- Authz and contract tests pass

## Phase 3: Normalizer and Validator (4-6 days)

Goal:
- Ensure AI output safely maps to current canvas contract

Deliverables:
1. Raw graph to canonical canvas normalizer
2. Graph and schema validator
3. Policy gate validator (adapters, timeout bounds, tenant rules)
4. Structured warnings and errors

Exit Gate:
- Compatibility tests pass for canonical canvas output

## Phase 4: Flow Builder Integration (3-5 days)

Goal:
- Integrate AI proposal workflow into current editor without disrupting manual flow path

Deliverables:
1. Generate with AI entry point
2. Proposal review panel
3. Open-to-draft integration with current flows model
4. Regression pass for manual flow operations

Exit Gate:
- Manual path unchanged and proposal path functional

## Phase 5: Observability and Operational Controls (2-3 days)

Goal:
- Add telemetry, logging, and runbook controls for safe rollout

Deliverables:
1. Proposal lifecycle telemetry events
2. Dashboard metrics and failure analysis
3. Operational runbook updates
4. Rollback checklist

Exit Gate:
- Ops validation completed

## Phase 6: Controlled Rollout (1-2 weeks)

Goal:
- Enable in production with minimal blast radius

Deliverables:
1. Internal-only release
2. Tenant allow-list rollout stages
3. Weekly quality and reliability review
4. Expansion decision report

Exit Gate:
- Stable metrics and no regression in current flow operations

## 4. Dependency Order

1. Persistence
2. Lifecycle service
3. APIs
4. Normalizer and validator
5. UI integration
6. Observability and rollout

## 5. Key Risks and Mitigations

1. Incompatible AI graph output
- Mitigation: strict normalizer and hard validation fail

2. Approval bypass risk
- Mitigation: service-level approval gate before publish path access

3. Tenant policy drift
- Mitigation: tenant policy source-of-truth and allow-list enforcement

4. Confusion between proposal and published flow
- Mitigation: clear status model and UI badges

## 6. Program Success Metrics

1. No regressions in manual flow save/publish path
2. Proposal validation pass rate target >= 80 percent after tuning
3. Approval-to-publish conversion target >= 50 percent for internal users
4. Zero unauthorized publish events
5. Zero runtime incidents attributable to proposal-path changes