docs: start milestone v3.0 Phishing Triage Automation

.planning/PROJECT.md

@@ -15,28 +15,55 @@ A manager can open Pulse on their phone and, in under 30 seconds, see the
 state of the business and triage tickets — without ever needing to switch to
 desktop for read-only awareness.
 
-## Current Milestone: v2.0 PAX8 Integration
+## Current Milestone: v3.0 Phishing Triage Automation
 
-**Goal:** Sync PAX8 licensing/subscription data into Pulse, read-only, mapped
-to Autotask companies, so managers can see subscription costs and seat counts
-alongside existing company data.
+**Goal:** Detect candidate phishing/spam report tickets in Autotask, extract
+and parse original-message evidence, classify each as `SPAM` / `UNWANTED` /
+`THREAT`, group duplicate reports into campaigns, and prepare (never
+auto-execute) remediation actions behind an explicit human-approval gate.
 
 **Target features:**
-- PAX8 client + factory (OAuth2 client-credentials; credentials already
-  provisioned)
-- Read-only sync of companies, subscriptions, product catalog, and
-  orders/invoices into Postgres
-- Fuzzy-name matching of PAX8 companies to Autotask companies, with a
-  manual-review path for unmatched/ambiguous cases
-- New `/pax8` page (company list, subscriptions, cost breakdown)
-- Daily sync via the existing scheduler pattern
+- Ticket detector/scanner matching known phishing/spam-report patterns
+  (title/body keyword + Microsoft/KnowBe4 report signatures), idempotent
+  reprocessing
+- `.eml` evidence extraction — prefers `rfc.eml` (original reported message)
+  over `OriginatingEmail.eml` (wrapper), case-insensitive name + `message/rfc822`
+  content-type matching
+- RFC822/MIME parser producing normalized headers (From/Reply-To/Return-Path/
+  To/Cc/Subject/Date/Message-ID/Received chain/auth results), URLs, and
+  attachment metadata (name/type/size/hash) — no URL detonation
+- Campaign grouping/dedupe keyed on Message-ID, then attachment-hash/URL-domain
+  + subject + sender + time-window, then sender + normalized subject + client
+  + time-window
+- Durable data model: campaigns, reports, messages, indicators, classifications,
+  remediation_actions, audit_events
+- Mimecast blast-radius lookup abstraction (interface + normalized output),
+  gracefully `unavailable` when unconfigured — classification still proceeds
+  on ticket/email evidence alone
+- Classifier service: deterministic rule layer + an LLM-abstraction plug point
+  (safe rule-based fallback if no LLM abstraction fits); structured evidence
+  in, not raw unbounded email; KnowBe4 simulations not auto-flagged as THREAT
+- API surface under `/api/phishing/*`: list/get campaigns, analyze a ticket,
+  classify/approve/remediate/mark-false-positive a campaign
+- Optional Autotask internal triage note (only if a safe note-write path
+  already exists; otherwise return note text via API)
+- Remediation safety: destructive actions (purge/delete/block/reset) always
+  `requires_approval: true`, logged with approver/timestamp/params/result,
+  idempotent on re-run, fail closed if approval/config missing
+- Tests: detection patterns, `.eml` selection logic, MIME parsing, campaign
+  dedupe, rule classification (SPAM/UNWANTED/THREAT), approval-required
+  safety, idempotent reprocessing, API happy-path + permission failures —
+  synthetic fixtures only, no real customer email
 
-Unrelated in domain to the v1.0 Mobile Shell Redesign above — this milestone
-adds a new backend integration and admin-facing surface, not a mobile change.
-See `.planning/seeds/SEED-002-pax8-integration.md` for the exploration that
-scoped this milestone. `.planning/seeds/SEED-003-general-pulse-data-assistant.md`
-(NL chatbot over Pulse data) is explicitly out of scope here — a separate
-future milestone that will consume this data once it exists.
+Unrelated in domain to the v2.0 PAX8 Integration above — this milestone adds a
+new security/triage backend feature (Autotask ticket + email evidence, not
+subscription billing). No seeds matched this scope; introduced directly from
+a detailed spec provided at milestone-start.
+
+**Non-goals:** no automatic tenant-wide purge, no automatic password
+reset/session revocation, no URL sandbox/detonation, no fully automated ticket
+closure, no assumption that Graph is the eventual purge mechanism (Defender/
+Exchange purge may be preferable later).
 
 ## Requirements
 
@@ -187,9 +214,19 @@ future milestone that will consume this data once it exists.
 
 ### Active
 
-<!-- Hypotheses for this milestone — see .planning/seeds/SEED-002-pax8-integration.md -->
+<!-- Hypotheses for this milestone — see .planning/REQUIREMENTS.md for the full v3.0 requirement list -->
 
-None — all v2.0 PAX8 Integration hypotheses validated above. Milestone complete.
+- Phishing/spam report tickets in Autotask can be reliably detected from
+  title/body patterns and reprocessed idempotently
+- `.eml` evidence (when present) can be parsed into normalized, actionable
+  indicators without executing/fetching anything suspicious
+- Duplicate reports of the same campaign can be grouped via a small set of
+  stable keys (Message-ID → indicator/subject/sender/window → sender/subject/
+  client/window)
+- A rule-based classifier (with a clean LLM plug-point) can produce a useful
+  SPAM/UNWANTED/THREAT verdict from structured evidence alone
+- Remediation can be modeled and gated behind approval without ever executing
+  destructively in this milestone
 
 ### Out of Scope
 
@@ -277,4 +314,4 @@ This document evolves at phase transitions and milestone boundaries.
 4. Update Context with current state
 
 ---
-*Last updated: 2026-07-12 — Phase 14: /pax8 UI Surface complete — v2.0 PAX8 Integration milestone complete*
+*Last updated: 2026-07-14 — v3.0 Phishing Triage Automation milestone started*

.planning/STATE.md

@@ -1,17 +1,16 @@
 ---
 gsd_state_version: 1.0
-milestone: v2.0
-milestone_name: PAX8 Integration
-status: milestone_complete
-stopped_at: Milestone complete (Phase 14 was final phase)
-last_updated: 2026-07-12T22:29:05.191Z
-last_activity: 2026-07-11 -- Phase 14 execution started
+milestone: v3.0
+milestone_name: Phishing Triage Automation
+status: planning
+last_updated: "2026-07-15T03:33:51.575Z"
+last_activity: 2026-07-15
 progress:
-  total_phases: 5
-  completed_phases: 4
-  total_plans: 20
-  completed_plans: 20
-  percent: 80
+  total_phases: 0
+  completed_phases: 0
+  total_plans: 0
+  completed_plans: 0
+  percent: 0
 ---
 
 # Project State
@@ -25,12 +24,10 @@ See: .planning/PROJECT.md (updated 2026-07-10)
 
 ## Current Position
 
-Phase: 14
-Plan: Not started
-Status: Milestone complete
-Last activity: 2026-07-12
-
-Progress: [░░░░░░░░░░] 0%
+Phase: Not started (defining requirements)
+Plan: —
+Status: Defining requirements
+Last activity: 2026-07-15 — Milestone v3.0 started
 
 ## Performance Metrics