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.