docs/production-roadmap.md

Guardian Agent Production Roadmap

This document turns the product-direction guidance into an execution backlog mapped to the current codebase.

The intended production shape is:

• the browser extension is the primary product surface
• the website supports onboarding, trust history, demo flows, and operator visibility
• Guardian uses a shared staged detection pipeline instead of separate demo logic
• risky actions stay behind explicit user approval gates

Product Focus

The first production use case should be travel checkout protection:

• hotels
• airlines
• vacation rentals

Why this focus:

• hidden fees are common and expensive
• urgency and scarcity patterns are frequent
• users understand the pain immediately
• the extension can deliver value without needing full autonomous purchase behavior

P0: Trustworthy Core

These items should happen before broad rollout.

P0.1 Shared Detection Pipeline

Goal:

• make Quick scan, Mission, and extension analysis use one production detection pipeline

Current files:

• artifacts/api-server/src/routes/demo/index.ts
• artifacts/api-server/src/routes/agent/index.ts
• artifacts/api-server/src/routes/mock.ts
• artifacts/api-server/src/lib/agentic-mission.ts
• artifacts/api-server/src/lib/ai-copilot.ts

Tasks:

• extract a shared analyzeCheckoutContext() service
• separate the pipeline into stages:
  • page classification
  • signal extraction
  • risk reasoning
  • recommendation
• make demo and mission endpoints thin wrappers around that shared service

Definition of done:

• one source of truth for manipulation detection
• one source of truth for confidence scoring
• one source of truth for non-commerce gating

P0.2 Non-Commerce and Page-Type Detection

Goal:

• reduce false positives before any model or trust score is shown

Current files:

• artifacts/api-server/src/lib/agentic-mission.ts
• artifacts/guardian-extension/content-script.js

Tasks:

• add page types:
  • non-commerce
  • product
  • cart
  • checkout
  • post-purchase
• require stronger evidence before running full detection on unknown domains
• make extension auto-activation depend on page type, not just heuristics

Definition of done:

• GitHub, docs, blogs, and normal browsing do not trigger shopping analysis
• cart and checkout pages activate reliably

P0.3 PII Redaction

Goal:

• never ship sensitive checkout data to the backend unintentionally

Current files:

• artifacts/guardian-extension/content-script.js
• artifacts/api-server/src/app.ts
• artifacts/api-server/src/lib/logger.ts

Tasks:

• strip or mask:
  • emails
  • phone numbers
  • addresses
  • payment details
  • loyalty numbers
  • traveler names
• add a browser-side sanitizer before payload submission
• add backend log redaction for request bodies

Definition of done:

• extension only sends checkout-relevant snippets
• backend logs are safe by default

P0.4 Deterministic Rules Before Model Calls

Goal:

• use AI where judgment is needed, not where rules are enough

Current files:

• artifacts/api-server/src/routes/demo/index.ts
• artifacts/api-server/src/lib/ai-copilot.ts

Tasks:

• add deterministic detectors for:
  • pre-checked add-ons
  • countdown text
  • low-stock phrasing
  • hidden fee labels
  • decline button prominence issues
• only call the model for higher-level synthesis and ambiguous cases

Definition of done:

• obvious issues do not depend on LLM output
• model usage becomes cheaper and more stable

P0.5 Confidence and Uncertainty

Goal:

• never fake certainty

Current files:

• artifacts/api-server/src/lib/ai-copilot.ts
• artifacts/guardian-agent/src/components/ai-copilot-card.tsx
• artifacts/guardian-extension/popup.js

Tasks:

• add field-level confidence to major findings
• add an explicit uncertain state when evidence is weak
• distinguish:
  • deterministic findings
  • AI-inferred findings
  • estimated totals

Definition of done:

• user can tell what Guardian knows vs. what it estimates

P1: Make the Extension Real

These items make the extension feel production-ready.

P1.1 SPA Handling and Dynamic Checkout Updates

Current files:

• artifacts/guardian-extension/content-script.js

Tasks:

• listen for SPA route changes
• reset stale overlay state when the page context changes
• add mutation observers for dynamic checkouts

Definition of done:

• Guardian reacts correctly on Amazon, airline flows, and React/Next/Vue sites

P1.2 Stronger DOM Targeting

Current files:

• artifacts/guardian-extension/content-script.js

Tasks:

• build element scoring from:
  • role
  • label
  • position
  • visibility
  • clickability
  • checked state
• improve DOM highlighting with evidence labels
• prefer visible actionable controls over generic text nodes

Definition of done:

• highlights land on the actual suspicious controls, not just nearby text

P1.3 Supervised Browser Workflow

Current files:

• artifacts/guardian-extension/background.js
• artifacts/api-server/src/lib/agentic-mission.ts

Tasks:

• model the browser workflow explicitly:
  • inspect
  • compare
  • strip upsells
  • ask for approval
• keep approval gates for:
  • account creation
  • credential submission
  • merchant switching
  • purchases

Definition of done:

• Guardian acts like a supervised assistant, not an unsafe autobuyer

P1: Backend Hardening

P1.4 Auth, Rate Limits, and Timeouts

Current files:

• artifacts/api-server/src/app.ts
• artifacts/api-server/src/index.ts

Tasks:

• add auth for non-local mode
• add per-IP or per-user rate limits
• add request timeouts
• add retries and circuit breakers for model dependencies

Definition of done:

• backend remains stable under failure and misuse

P1.5 Observability

Current files:

• artifacts/api-server/src/lib/logger.ts
• artifacts/api-server/src/app.ts

Tasks:

• add request ids across frontend, extension, and backend
• log model latency and failure rates
• log false-positive feedback events
• log extension activation success

Definition of done:

• major failures can be debugged from logs and traces

P2: Trust System and Data Layer

P2.1 Domain Evidence History

Current files:

• artifacts/api-server/src/routes/trust
• artifacts/api-server/src/routes/reports
• artifacts/guardian-agent/src/pages/trust

Tasks:

• accumulate repeated evidence for each domain
• track:
  • pattern counts
  • fee estimates
  • user feedback
  • scan timestamps
• expose score explanations on trust pages

Definition of done:

• trust score becomes explainable and longitudinal

P2.2 Score Versioning

Current files:

• artifacts/api-server/src/lib/agentic-mission.ts
• trust/report persistence layer once normalized

Tasks:

• assign a scoring version to every trust result
• explain why a domain score changed over time

Definition of done:

• users and operators can audit trust changes

P2: Frontend and UX

P2.3 Show Evidence, Why, and What To Do

Current files:

• artifacts/guardian-agent/src/pages/demo.tsx
• artifacts/guardian-agent/src/pages/feecalc.tsx
• artifacts/guardian-agent/src/pages/agent.tsx
• artifacts/guardian-agent/src/components/ai-copilot-card.tsx

Tasks:

• label each output as:
  • deterministic
  • AI-inferred
  • estimated
• show user action guidance on every warning
• keep uncertainty visible

Definition of done:

• product feels honest, not overconfident

P2: Testing

P2.4 Extension and Backend Test Corpus

Current files:

• tests
• new fixture directories should be added under tests/fixtures

Tasks:

• create a fixture corpus for:
  • hotel checkout
  • airline upsells
  • vacation rentals
  • non-commerce pages
• add regression cases for:
  • false positives
  • false negatives
  • non-commerce misclassification

Definition of done:

• the team can add a broken example and keep it fixed

P2.5 Extension E2E

Suggested new folder:

• artifacts/guardian-extension/tests

Tasks:

• add end-to-end tests for:
  • popup -> content script -> backend flow
  • SPA route changes
  • non-commerce suppression
  • DOM highlighting

Definition of done:

• extension behavior can be validated automatically before release

P2: Infra and Deployment

P2.6 CI and Release Discipline

Current files:

• root workspace scripts in package.json

Tasks:

• add CI for:
  • lint
  • typecheck
  • backend tests
  • extension tests
  • Docker build
• version the extension and backend API intentionally together
• add environment separation:
  • local
  • staging
  • production

Definition of done:

• every release is reproducible and tested

Compliance and Legal

This should be handled continuously, not as a late-stage task.

Requirements:

• present Guardian as user-side assistance, not bot abuse
• do not automate purchases without explicit approval
• do not silently create accounts or submit credentials
• publish clear privacy and retention rules

Recommended Order of Execution

If only five items are started next, do these first:

1. P0.1 shared detection pipeline
2. P0.2 non-commerce and page-type detection
3. P0.3 PII redaction
4. P2.4 fixture corpus and regression tests
5. P1.4 backend hardening and observability