From 05c18e7f7bd4eafb825cc32050a1563b1500dec2 Mon Sep 17 00:00:00 2001
From: mpmedia <mpm@mpmedia.tv>
Date: Sun, 7 Jun 2026 10:45:59 -0500
Subject: [PATCH] Add example: project roadmap (sanitized)

---
 examples/project_roadmap_example.md | 88 +++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 examples/project_roadmap_example.md

diff --git a/examples/project_roadmap_example.md b/examples/project_roadmap_example.md
new file mode 100644
index 0000000..7a9ac09
--- /dev/null
+++ b/examples/project_roadmap_example.md
@@ -0,0 +1,88 @@
+# Gmail Inbox Architect — Example Project Roadmap
+
+> **Note:** This is a sanitized example showing the structure and decisions
+> produced by a completed Phase 1 + Phase 2 run of the Gmail Inbox Architect plugin.
+> Replace bracketed placeholders with your own project values.
+
+**Status:** Phase 1 complete, Phase 2 deployed, Phase 3 planning
+
+---
+
+## What's Done
+
+### Phase 1 — Filter Activation (Complete)
+- [N] Gmail filters live across [M] label trees (Support, Finance, Notifications,
+  Operations, Vendors, Clients/Resellers, Development, Marketing, Personal, Sales, Travel)
+- [N] new Gmail labels created
+- Master Tracker tracking all rules: `Tracker.xlsx`
+
+### Phase 2 — Apps Script Attachment Scanner (Complete)
+- Deployed: `scanDocumentationAttachments()` — hourly trigger
+- Catches `.STP`/`.STEP` files and diagram+PDF combos → applies `Documentation` label
+- Guard label `Z-Archive/DocScan` (hidden) prevents re-scanning
+- No star/Studio trigger — verification-only in current form
+
+### Cleanup Completed
+- ✅ [Example: mark-read enabled for a high-volume noise sender]
+- ✅ [Example: legacy label backfilled and deprecated]
+
+---
+
+## Open Backlog
+
+### Immediate / Low Effort
+
+| Item | Notes |
+|---|---|
+| Delete deprecated legacy label | Label is empty after backfill. Remove when ready. |
+| `! Rule Needed` periodic review | Run with architect agent when label accumulates candidates |
+| Deferred rule (e.g. seasonal vendor) | Held at `do_not_automate_yet`. Revisit when activity resumes. |
+
+### Apps Script Extensions (Medium Effort)
+
+| Document Type | Detection Pattern | Target Label |
+|---|---|---|
+| Vendor invoices | `filename: /inv[-_]\d+\.pdf/i` | Finance/Invoices-Vendor-Payable |
+| Purchase orders | `filename: /po[-_\s]?\d+\|purchase.order/i` | Finance/Purchase-Orders |
+| Signed contracts | `filename: /signed\|executed/i` + PDF | Documentation |
+| Shipping manifests | `filename: /manifest\|packing.list/i` | Vendors/Shipping |
+| Quotes/proposals | `filename: /quote\|proposal\|rfq/i` + PDF | Sales/Quotes |
+
+### Phase 3 — Real-Time Studio Integration (Future)
+
+| Item | Notes |
+|---|---|
+| Gmail `watch()` API | Pub/Sub + webhook for near-real-time Apps Script triggering |
+| AI processing layer | Route starred/queued messages through Claude for triage |
+| Morning brief integration | Pull high-signal classified mail into daily brief |
+
+---
+
+## ! Rule Needed Process
+
+**What it is:** A Gmail label applied manually when an email arrives that should have
+an automated rule but doesn't.
+
+**Review cadence:** Ad hoc — run when label accumulates enough candidates.
+
+**Session flow:**
+1. Pull all messages in `! Rule Needed`
+2. Review senders, subjects, patterns
+3. Determine: gmail_filter_safe or apps_script_needed?
+4. Draft rules, add to Tracker, deploy
+5. Remove `! Rule Needed` label from processed threads
+
+---
+
+## Key Decisions on Record
+
+- **apps_script_needed** = attachment filename inspection only. Multi-domain OR queries
+  are gmail_filter_safe — Gmail's query field handles these natively.
+- **Studio timing constraint:** Stars applied by Apps Script don't trigger Studio flows.
+  Star must come from a Gmail filter at receipt time. Apps Script stars are schedule-driven,
+  not receipt-driven.
+- **Single-label-per-filter:** Required to avoid Gmail API rate limits on parallel creation.
+- **Participant-domain pattern:** `from:(domain.com) OR to:(domain.com) OR cc:(domain.com)`
+  — use for business relationships. From-only for inbound-only services (card issuers, SaaS).
+- **End-customer domains:** Do not auto-rule domains that appear adjacent to a client without
+  confirming the relationship is consistent. Flag with `! Rule Needed` first.