docs/dev/pots_workspace_40_phase_project_map.md

# POTS Workspace 40-Phase Project Map

## Purpose
Create a single enterprise-grade POTS replacement workspace that can run as a quick estimator or full onboarding workflow, supports save/resume, supports delegated completion, and generates complete quote/survey artifacts for Masters Telecom operations.

## Scope Guardrails
- Keep existing policy/guardrail behavior and hard timeout behavior unchanged unless a phase explicitly targets guardrail improvements.
- Do not implement this deferred backlog item in this cycle: `Paste order lines parser (5 CR602, 2 RX60) to auto-fill quantities/models`.
- External customer contribution flow is deferred to **Phase 2+** (not in Phase 1 execution).

## Operating Model
- One commit per phase (or split only if phase is too large).
- Each phase must end with explicit verification commands and pass/fail report.
- Keep docs synced each phase:
  - `docs/dev/session_handoff.md`
  - `docs/dev/decisions.md`
  - `docs/dev/open_tasks.md`

## Execution Status (2026-03-06)
- `Phase 1-8`: complete
- `Phase 9-16`: complete (see `docs/dev/pots_workspace_phase9_16_guided_intake.md`)
- `Phase 17-24`: complete (see `docs/dev/pots_workspace_phase17_24_quote_financial.md`)
- `Phase 25-32`: complete (see `docs/dev/pots_workspace_phase25_32_collaboration_ai.md`)
- `Phase 33-40`: complete (see `docs/dev/pots_workspace_phase33_40_readiness_launch.md`)

## Phase Tracks
- Track A (`1-8`): Foundation and orchestration shell.
- Track B (`9-16`): Guided discovery and site/line intake UX.
- Track C (`17-24`): BOM, quote, and financial workflow.
- Track D (`25-32`): Collaboration, handoff, and AI acceleration.
- Track E (`33-40`): Quality, compliance, deployment, and adoption.

## Detailed Phases

### Phase 1 - Workspace Foundation API + Shell
- Goal: establish project-backed workspace skeleton scoped per authenticated user.
- Build:
  - backend project store API (`create/list/get/update`), triage endpoint, estimate snapshot endpoint.
  - frontend POTS workspace shell wrapping existing estimator/intake tabs.
  - owner scoping so one user cannot see another user’s workspace records.
- Verification:
  - `python3 -m pytest -q backend/app/test_pots_workspace_api.py`
  - `npm --prefix frontend run build`
- Exit criteria:
  - project can be created/re-opened in workspace.
  - triage recommendation is saved to project record.

### Phase 2 - Roles + Collaboration Model (Internal-first)
- Goal: finalize who can create/edit/review and what collaboration means in-app.
- Build:
  - role matrix for Verizon rep vs Masters employee actions.
  - contribution boundaries for delegated completion (internal first).
  - explicit deferral decision on external customer contribution path.
- Verification:
  - architecture note + acceptance checklist signed.
- Exit criteria:
  - role/collaboration contract documented and approved.

### Phase 3 - Project Lifecycle States
- Goal: define deterministic project state machine.
- Build:
  - statuses (`draft`, `discovery`, `needs_survey`, `estimating`, `ready_for_review`, `handoff_ready`, `closed`).
  - state transition guards and reason codes.
- Verification:
  - state-machine unit tests.
- Exit criteria:
  - invalid transitions are blocked with actionable reason text.

### Phase 4 - Tenant/User Data Isolation Hardening
- Goal: harden per-user and per-account isolation behavior.
- Build:
  - storage partition rules.
  - API-level isolation tests.
  - secure fallback behavior when auth context is missing.
- Verification:
  - auth-context simulation tests with mixed users.
- Exit criteria:
  - zero cross-user data leakage in tests.

### Phase 5 - Workspace Home UX
- Goal: make project home highly usable and plain-English.
- Build:
  - “start quick estimate” vs “run full onboarding” cards.
  - recent projects, status chips, next-action cards.
- Verification:
  - responsive UI validation on desktop/tablet/mobile.
- Exit criteria:
  - users can start or resume in <=2 clicks.

### Phase 6 - Intake Progress Model
- Goal: normalize progress tracking for partially known answers.
- Build:
  - per-question status (`answered`, `unknown`, `deferred`, `needs_owner`).
  - completion score by section.
- Verification:
  - progress-calculation unit tests.
- Exit criteria:
  - project completion reflects unknown/deferred answers correctly.

### Phase 7 - Delegation Skeleton (Internal Contributors)
- Goal: allow reassignment of unanswered sections to internal teammates.
- Build:
  - assign question/section owner.
  - notify in workspace activity feed.
- Verification:
  - assignment and visibility tests.
- Exit criteria:
  - delegated sections persist and route to right owner.

### Phase 8 - Audit Log v1
- Goal: capture defensible audit trail.
- Build:
  - immutable timeline events (created, edited, assigned, submitted).
- Verification:
  - event ordering and integrity tests.
- Exit criteria:
  - key actions are fully traceable.

### Phase 9 - Guided Discovery Question Tree v1
- Goal: provide adaptive question-by-question flow.
- Build:
  - branching logic based on line types and known/unknown answers.
- Verification:
  - branch-coverage tests.
- Exit criteria:
  - no dead-end question paths.

### Phase 10 - Multi-Location Wizard
- Goal: support one-to-many locations with repeatable templates.
- Build:
  - add/remove location flow.
  - clone prior location skeleton.
- Verification:
  - wizard integration tests.
- Exit criteria:
  - users can create projects with variable site counts.

### Phase 11 - Line Inventory Capture v1
- Goal: capture line inventory in structured model.
- Build:
  - line types, criticality, current provider, notes.
- Verification:
  - schema validation tests.
- Exit criteria:
  - all required minimum fields captured for estimate path.

### Phase 12 - “I Don’t Know” Pathways
- Goal: remove friction when customer does not know details.
- Build:
  - explicit unknown states and follow-up requirements.
  - unresolved-question report.
- Verification:
  - unknown-path regression tests.
- Exit criteria:
  - users can continue without blocking on unknowns.

### Phase 13 - Survey-Now vs Survey-Later Routing
- Goal: support both immediate and deferred survey intent.
- Build:
  - route selection and saved intent.
  - follow-up checklist based on chosen route.
- Verification:
  - route persistence tests.
- Exit criteria:
  - route choice consistently controls next workflow.

### Phase 14 - Site Survey Packet Generator v1
- Goal: generate actionable survey tasks from missing fields.
- Build:
  - per-site survey checklist output.
- Verification:
  - checklist generation tests.
- Exit criteria:
  - unresolved site requirements are exportable.

### Phase 15 - Critical Endpoint Heuristics
- Goal: detect life-safety/critical-path lines and elevate priority.
- Build:
  - rule-based criticality scoring.
- Verification:
  - deterministic rule tests.
- Exit criteria:
  - critical lines flagged in UX and exports.

### Phase 16 - Intake QA Guardrails
- Goal: prevent invalid or contradictory intake payloads.
- Build:
  - cross-field validations and warning tiers.
- Verification:
  - invalid payload matrix tests.
- Exit criteria:
  - contradictory states blocked or clearly warned.

### Phase 17 - Estimate Engine Integration v2
- Goal: tie guided intake directly to estimator inputs.
- Build:
  - deterministic mapping from intake data to estimator payload.
- Verification:
  - mapper contract tests.
- Exit criteria:
  - estimator runs from project snapshot without manual re-entry.

### Phase 18 - Savings Scenario Builder
- Goal: support best/base/worst case scenarios.
- Build:
  - scenario assumptions with transparent labels.
- Verification:
  - scenario math tests.
- Exit criteria:
  - multi-scenario summary appears in project.

### Phase 19 - BOM Draft Generator v1
- Goal: generate initial BOM based on site/line profile.
- Build:
  - device + accessory + service placeholders.
- Verification:
  - BOM structure tests.
- Exit criteria:
  - BOM output generated with no fabricated pricing.

### Phase 20 - Missing Inputs Resolver
- Goal: identify exactly what is blocking quote readiness.
- Build:
  - blocking-input report with owner assignment.
- Verification:
  - blocker detection tests.
- Exit criteria:
  - users get clear next steps to become quote-ready.

### Phase 21 - Cost/Savings Narrative Generator
- Goal: produce plain-English business-case summary.
- Build:
  - deterministic narrative from estimate fields.
- Verification:
  - snapshot tests for narrative sections.
- Exit criteria:
  - summary is readable and source-backed.

### Phase 22 - Quote Review Checklist
- Goal: enforce quote quality before handoff.
- Build:
  - pre-submit checklist and validation gate.
- Verification:
  - checklist enforcement tests.
- Exit criteria:
  - handoff blocked until required checks complete.

### Phase 23 - Excel Export v2
- Goal: produce comprehensive workbook for operations and customer materials.
- Build:
  - tabs for sites, lines, assumptions, estimate summary, open items.
- Verification:
  - workbook content tests.
- Exit criteria:
  - export includes all required sections and consistent IDs.

### Phase 24 - PDF Summary Packet v1
- Goal: produce concise executive summary PDF.
- Build:
  - project overview, counts, savings highlights, next actions.
- Verification:
  - render and content smoke tests.
- Exit criteria:
  - packet is attachable and readable by non-technical stakeholders.

### Phase 25 - Save/Resume Reliability Hardening
- Goal: guarantee stable resume across sessions and tabs.
- Build:
  - durable autosave with conflict-safe merges.
- Verification:
  - resume regression tests.
- Exit criteria:
  - no data loss in interrupted sessions.

### Phase 26 - Workspace Activity Feed
- Goal: improve transparency across contributors.
- Build:
  - event feed with filters (changes, assignments, exports, submissions).
- Verification:
  - feed ordering tests.
- Exit criteria:
  - team can audit progress without opening every section.

### Phase 27 - Internal Handoff to Masters Ops
- Goal: formalize handoff package and API/event.
- Build:
  - handoff payload contract.
  - submission receipt tracking.
- Verification:
  - contract + integration tests.
- Exit criteria:
  - handoff package is complete and machine-parseable.

### Phase 28 - Follow-Up Task Queue
- Goal: manage outstanding items after handoff.
- Build:
  - owner, due date, status, notes.
- Verification:
  - queue workflow tests.
- Exit criteria:
  - unresolved dependencies are tracked until closure.

### Phase 29 - Notification Hooks
- Goal: notify contributors about assignments/status changes.
- Build:
  - in-app notification and optional email hook.
- Verification:
  - notification trigger tests.
- Exit criteria:
  - assigned users receive timely prompts.

### Phase 30 - Helper Bot Context Bridging
- Goal: let helper chatbots answer within active project context.
- Build:
  - project-context payload to helper endpoints.
- Verification:
  - context propagation tests.
- Exit criteria:
  - helper responses reference current project facts.

### Phase 31 - Plain-English Copilot Answers
- Goal: return full-sentence guidance with low jargon.
- Build:
  - response style contract and lint checks.
- Verification:
  - response-format tests.
- Exit criteria:
  - answers are concise, clear, and actionable.

### Phase 32 - External Research Assist (Guarded)
- Goal: support web-sourced insights only when internal docs are weak.
- Build:
  - explicit web-source labeling and confidence tiers.
- Verification:
  - source-labeling tests.
- Exit criteria:
  - web-sourced content is clearly marked and not mixed silently.

### Phase 33 - Performance Budgeting
- Goal: keep workspace responsive under realistic project sizes.
- Build:
  - latency budgets per endpoint/stage.
- Verification:
  - synthetic performance tests.
- Exit criteria:
  - p95 within agreed thresholds.

### Phase 34 - Error Recovery UX
- Goal: graceful recovery from network/API failures.
- Build:
  - retry flows, offline warnings, unsaved-change prompts.
- Verification:
  - failure-mode UI tests.
- Exit criteria:
  - no silent failures, clear recovery path always present.

### Phase 35 - Security & PII Logging Review
- Goal: ensure SOC2-style defaults remain enforced.
- Build:
  - PII-safe logging checks, token-handling review, secret scan.
- Verification:
  - security checklist and tests.
- Exit criteria:
  - no sensitive data leakage in logs or client payloads.

### Phase 36 - Contract Freeze for Integrations
- Goal: freeze API + export contracts for dependent teams.
- Build:
  - versioned contracts and migration notes.
- Verification:
  - contract snapshot tests.
- Exit criteria:
  - downstream integrations can adopt without breakage.

### Phase 37 - UAT Pilot (Internal Sales + SE)
- Goal: validate with real workflows and feedback loops.
- Build:
  - pilot script, scoring rubric, issue triage board.
- Verification:
  - pilot completion report.
- Exit criteria:
  - blockers triaged and prioritized.

### Phase 38 - Enablement Package
- Goal: prepare launch materials for internal teams.
- Build:
  - quick-start guide, walkthrough video/script, FAQ.
- Verification:
  - dry-run with pilot users.
- Exit criteria:
  - new users can onboard without live handholding.

### Phase 39 - Production Readiness Gate
- Goal: go/no-go with measurable criteria.
- Build:
  - readiness checklist across quality, security, performance, support.
- Verification:
  - gate sign-off artifact.
- Exit criteria:
  - release criteria explicitly met.

### Phase 40 - Launch + Continuous Optimization
- Goal: release and establish operating cadence.
- Build:
  - launch metrics dashboard.
  - weekly optimization backlog loop.
- Verification:
  - first 30-day adoption and cycle-time report.
- Exit criteria:
  - measurable reduction in quote cycle time and rework.

## Immediate Execution (Now)
- Start with **Phase 1** implementation in this cycle.
- Keep external customer contribution design in **Phase 2** as requested.