Spaces:
Sleeping
Sleeping
| # 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](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/api-server/src/routes/demo/index.ts) | |
| - [artifacts/api-server/src/routes/agent/index.ts](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/api-server/src/routes/agent/index.ts) | |
| - [artifacts/api-server/src/routes/mock.ts](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/api-server/src/routes/mock.ts) | |
| - [artifacts/api-server/src/lib/agentic-mission.ts](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/api-server/src/lib/agentic-mission.ts) | |
| - [artifacts/api-server/src/lib/ai-copilot.ts](/d:/Projects/Guardian-Agent/Guardian-Agent/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](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/api-server/src/lib/agentic-mission.ts) | |
| - [artifacts/guardian-extension/content-script.js](/d:/Projects/Guardian-Agent/Guardian-Agent/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](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/guardian-extension/content-script.js) | |
| - [artifacts/api-server/src/app.ts](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/api-server/src/app.ts) | |
| - [artifacts/api-server/src/lib/logger.ts](/d:/Projects/Guardian-Agent/Guardian-Agent/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](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/api-server/src/routes/demo/index.ts) | |
| - [artifacts/api-server/src/lib/ai-copilot.ts](/d:/Projects/Guardian-Agent/Guardian-Agent/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](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/api-server/src/lib/ai-copilot.ts) | |
| - [artifacts/guardian-agent/src/components/ai-copilot-card.tsx](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/guardian-agent/src/components/ai-copilot-card.tsx) | |
| - [artifacts/guardian-extension/popup.js](/d:/Projects/Guardian-Agent/Guardian-Agent/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](/d:/Projects/Guardian-Agent/Guardian-Agent/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](/d:/Projects/Guardian-Agent/Guardian-Agent/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](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/guardian-extension/background.js) | |
| - [artifacts/api-server/src/lib/agentic-mission.ts](/d:/Projects/Guardian-Agent/Guardian-Agent/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](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/api-server/src/app.ts) | |
| - [artifacts/api-server/src/index.ts](/d:/Projects/Guardian-Agent/Guardian-Agent/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](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/api-server/src/lib/logger.ts) | |
| - [artifacts/api-server/src/app.ts](/d:/Projects/Guardian-Agent/Guardian-Agent/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](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/api-server/src/routes/trust) | |
| - [artifacts/api-server/src/routes/reports](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/api-server/src/routes/reports) | |
| - [artifacts/guardian-agent/src/pages/trust](/d:/Projects/Guardian-Agent/Guardian-Agent/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](/d:/Projects/Guardian-Agent/Guardian-Agent/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](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/guardian-agent/src/pages/demo.tsx) | |
| - [artifacts/guardian-agent/src/pages/feecalc.tsx](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/guardian-agent/src/pages/feecalc.tsx) | |
| - [artifacts/guardian-agent/src/pages/agent.tsx](/d:/Projects/Guardian-Agent/Guardian-Agent/artifacts/guardian-agent/src/pages/agent.tsx) | |
| - [artifacts/guardian-agent/src/components/ai-copilot-card.tsx](/d:/Projects/Guardian-Agent/Guardian-Agent/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](/d:/Projects/Guardian-Agent/Guardian-Agent/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](/d:/Projects/Guardian-Agent/Guardian-Agent/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 | |