feat(classifier): add tag-based retention and 2-way rules sync engine

GEMINI.md

@@ -1 +1,5 @@
-@./AGENTS.md
+# GEMINI.md
+
+This repository follows the development and agentic architecture standards defined in [AGENTS.md](AGENTS.md) and [`petry-projects/.github/AGENTS.md`](https://github.com/petry-projects/.github/blob/main/AGENTS.md).
+
+Read [AGENTS.md](AGENTS.md) for full context, project conventions, testing guidelines, and architectural rules.

docs/proposals/proposal-001-ai-gemini-semantic-classifier.md

@@ -92,15 +92,15 @@ The `Gmail.Users.Settings.Filters.create` call additionally requires the **Advan
 
 The classifier operates against a standardized, mutually exclusive, collectively exhaustive (MECE) 7-domain taxonomy:
 
-| 7 Canonical Domains          | Standard PARA Area            | Scope & Contents                                                                       |
-| :--------------------------- | :---------------------------- | :------------------------------------------------------------------------------------- |
-| **`01_Household`**           | Real Estate & Living Space    | Primary residence, secondary properties, rental properties, property archives          |
-| **`02_Finance_Legal`**       | Financial & Legal Protections | Taxes, banking, insurance policies, court records, custody, estate planning            |
-| **`03_Vehicles`**            | Transportation & Assets       | Vehicle searches, vehicle titles, maintenance logs                                     |
-| **`04_Family_Health`**       | Family Welfare & Health       | Children, school records, medical appointments, therapy sessions, educational programs |
-| **`05_Tech_Infrastructure`** | IT & Home Automation          | Home automation, NAS backups, scripting tools, network gear, software licenses         |
-| **`06_Work_Career`**         | Professional Life & Income    | Employment records, resumes, interview materials, expense reports, admin notes         |
-| **`07_Community_NonProfit`** | Civic Duty & Service          | Charity organizations, community board roles, faith outreach                           |
+| 7 Canonical Domains           | Standard PARA Area            | Scope & Contents                                                                       |
+| :---------------------------- | :---------------------------- | :------------------------------------------------------------------------------------- |
+| **`01_Household`**            | Real Estate & Living Space    | Primary residence, secondary properties, rental properties, property archives          |
+| **`02_Finance_Legal`**        | Financial & Legal Protections | Taxes, banking, insurance policies, court records, custody, estate planning            |
+| **`03_Vehicles`**             | Transportation & Assets       | Vehicle searches, vehicle titles, maintenance logs                                     |
+| **`04_Family_Health_School`** | Family Welfare & Health       | Children, school records, medical appointments, therapy sessions, educational programs |
+| **`05_Tech_Infrastructure`**  | IT & Home Automation          | Home automation, NAS backups, scripting tools, network gear, software licenses         |
+| **`06_Work_Career`**          | Professional Life & Income    | Employment records, resumes, interview materials, expense reports, admin notes         |
+| **`07_Community_NonProfit`**  | Civic Duty & Service          | Charity organizations, community board roles, faith outreach                           |
 
 ---
 
@@ -137,7 +137,7 @@ When Gemini classifies a new sender with high confidence (>= 95%), the script au
 **Confidence calibration and staged approval:**
 
 - Only classifications with `confidence >= autoFilterConfidenceThreshold` (default: `0.95`) trigger filter creation.
-- Senders categorized under sensitive domains (e.g., `02_Finance_Legal`, `04_Family_Health`) should be reviewed manually before trusting auto-generated filters in production.
+- Senders categorized under sensitive domains (e.g., `02_Finance_Legal`, `04_Family_Health_School`) should be reviewed manually before trusting auto-generated filters in production.
 
 **Duplicate filter detection:**
 
@@ -188,6 +188,6 @@ src/gmail-ai-classifier/
 
 ## Discussion & Tracking
 
-- Issue Tracked: [#491](https://github.com/petry-projects/google-app-scripts/issues/491)
-- Pull Request Tracked: [#492](https://github.com/petry-projects/google-app-scripts/pull/492)
-- Repository: `petry-projects/google-app-scripts`
+- Issue Tracked: [#491](https://github.com/open-source-projects/google-app-scripts/issues/491)
+- Pull Request Tracked: [#492](https://github.com/open-source-projects/google-app-scripts/pull/492)
+- Repository: `open-source-projects/google-app-scripts`

src/gmail-ai-classifier/README.md

@@ -6,26 +6,26 @@ A native Google Apps Script module that uses the Gemini REST API (`gemini-1.5-fl
 
 ## Multi-Account Household Deployment Guide (Option A)
 
-To run this classifier across multiple household Gmail accounts (`donpetry@gmail.com` and `rachel.l.petry@gmail.com`):
+To run this classifier across multiple household Gmail accounts (`partner@example.com` and `user@example.com`):
 
 ### 1. Share Google Drive Taxonomy Folders
 
-Share the 7 Canonical Domain folders in Google Drive (`01_Household` through `07_Community_NonProfit`) with full Editor access to `rachel.l.petry@gmail.com`.
+Share the 7 Canonical Domain folders in Google Drive (`01_Household` through `07_Community_NonProfit`) with full Editor access to `user@example.com`.
 
 ### 2. Deploy Apps Script Worker Project
 
-1. Log into Google Apps Script under `rachel.l.petry@gmail.com`.
+1. Log into Google Apps Script under `user@example.com`.
 2. Push or import this script repository (`google-app-scripts`).
 3. Set **Script Properties** under Project Settings:
    - `GEMINI_API_KEY`: Your Gemini API key.
-   - `GITHUB_PAT`: Personal Access Token with repo access to `don-petry/self-private`.
+   - `GITHUB_PAT`: Personal Access Token with repo access to `user-org/self-private`.
 4. Set Time-Driven Trigger: Run `processEmailsWithAiClassifier` every 15 minutes.
 
 ---
 
 ## Features
 
-- **Multi-Account Attribution**: Automatically tags entries with `- **Account**: rachel.l.petry@gmail.com` or `donpetry@gmail.com`.
+- **Multi-Account Attribution**: Automatically tags entries with `- **Account**: user@example.com` or `partner@example.com`.
 - **Semantic Email Classification**: Evaluates incoming senders and body snippets into canonical domains.
 - **Single Global `Processed` Marker**: Applies a single global `Processed` label to indicate Drive ingestion completion.
 - **Inbox Preservation**: Processing emails into Google Drive preserves message visibility in the INBOX for human review.

src/gmail-ai-classifier/code.gs

@@ -198,13 +198,13 @@ function classifyWithGemini(sender, subject, snippet, config) {
     JSON.stringify(config.canonicalDomains) +
     '.\n\n' +
     'STRICT CLASSIFICATION RULES:\n' +
-    "1. MEDIA & PLATFORM NEWSLETTERS (Medium, NYT, Substack, Epoch Times, LinkedIn digests, event/news blasts): Treat strictly as Promotional / Newsletter and return null for canonicalDomain. Do NOT classify under '06_Work_Career' or '04_Family_Health'. Set category to 'Promotions' or 'Social', action to 'keep'.\n" +
+    "1. MEDIA & PLATFORM NEWSLETTERS (Medium, NYT, Substack, Epoch Times, LinkedIn digests, event/news blasts): Treat strictly as Promotional / Newsletter and return null for canonicalDomain. Do NOT classify under '06_Work_Career' or '04_Family_Health_School'. Set category to 'Promotions' or 'Social', action to 'keep'.\n" +
     "2. UTILITY & TECH BILLS (AT&T, Google Cloud, Electric, Water): Classify under '02_Finance_Legal' (sub-label 'Finance/Banking') or '05_Tech_Infrastructure' (sub-label 'Tech/Alerts-Monitoring'). Set category to 'Updates', action to 'keep'.\n" +
-    "3. MARRIAGE & ADULT FAMILY (WinShape, Marriage retreats, DJ & Rachel personal): Classify under '04_Family_Health' (sub-label 'Family/DJ-Rachel'). Set category to 'Primary', action to 'keep'.\n" +
+    "3. MARRIAGE & ADULT FAMILY (WinShape, Marriage retreats, Spouse & Primary personal): Classify under '04_Family_Health_School' (sub-label 'Family/Spouse-Primary'). Set category to 'Primary', action to 'keep'.\n" +
     "4. BEEKEEPING & MYBROODMINDER ALERTS (MyBroodMinder, Hive telemetry alerts, BOD): Classify under '07_Community_NonProfit' (sub-label 'Projects/Beekeeping'). Set category to 'Updates', action to 'keep'.\n" +
-    "5. HEALTH NEWSLETTERS & MEDICAL BULLETINS (WebMD, Epoch Health, drug recall news digests): Treat as Newsletter and return null for canonicalDomain. Reserve '04_Family_Health' strictly for personal family medical records, doctor visits, patient portals, and school/kids health notes.\n" +
+    "5. HEALTH NEWSLETTERS & MEDICAL BULLETINS (WebMD, Epoch Health, drug recall news digests): Treat as Newsletter and return null for canonicalDomain. Reserve '04_Family_Health_School' strictly for personal family medical records, doctor visits, patient portals, and school/kids health notes.\n" +
     "6. E-COMMERCE PROMOTIONS & SOCIAL DIGESTS (Lowes, Nextdoor, American Meadows, Hydrobuilder): Return null for canonicalDomain. Set category to 'Promotions' or 'Social'.\n" +
-    "7. SCHOOL PORTALS & PARENTSQUARE (ParentSquare, Magic City Acceptance Academy, MCAA, school shuttle notifications, school attendance): Classify under '04_Family_Health' (sub-label 'Family/School-Toby'). Set category to 'Updates' or 'Primary', action to 'keep'.\n" +
+    "7. SCHOOL PORTALS & PARENTSQUARE (ParentSquare, Magic City Acceptance Academy, MCAA, school shuttle notifications, school attendance): Classify under '04_Family_Health_School' (sub-label 'Family/School-Child'). Set category to 'Updates' or 'Primary', action to 'keep'.\n" +
     "8. TECH WEBINARS & PRODUCT MARKETING (Google Cloud webinars, 'Register Now', product marketing, tech promos): Treat as Promotional / Marketing and return null for canonicalDomain. Reserve '05_Tech_Infrastructure' strictly for active system alerts, security warnings, spend cap notifications, and project quota/outage alerts.\n" +
     "9. HOBBY & STORE MARKETING (Lorob Bees, Foxhound Bee Company, e-commerce store newsletters, product announcements): Treat as Promotional / Marketing and return null for canonicalDomain. Reserve '07_Community_NonProfit' / 'Projects/Beekeeping' strictly for active hive telemetry alerts (MyBroodMinder) and official non-profit BOD communications.\n" +
     "10. SPAM & PHISHING & UNWANTED SOLICITATION: Set action to 'trash'.\n" +
@@ -218,7 +218,7 @@ function classifyWithGemini(sender, subject, snippet, config) {
     'Body Snippet: ' +
     snippet +
     '\n\n' +
-    'Return JSON ONLY: {"canonicalDomain": "04_Family_Health", "subLabel": "Family/School-Toby", "category": "Primary", "action": "keep", "confidence": 0.98, "title": "Short Title", "summary": "2 sentence executive summary"}\n' +
+    'Return JSON ONLY: {"canonicalDomain": "04_Family_Health_School", "subLabel": "Family/School-Child", "category": "Primary", "action": "keep", "confidence": 0.98, "title": "Short Title", "summary": "2 sentence executive summary"}\n' +
     "Valid categories: 'Primary', 'Updates', 'Promotions', 'Social', 'Forums'.\n" +
     "Valid actions: 'keep', 'archive', 'trash', 'mark_read'."
 
@@ -398,12 +398,12 @@ function createGmailFilterRule(senderEmail, targetLabelName) {
 
 function getNotePathForDomain(domain) {
   var map = {
-    '01_Household': 'petry-household/birmingham/index.md',
-    '02_Finance_Legal': 'petry-household/finances/index.md',
-    '03_Vehicles': 'petry-household/vehicles/index.md',
-    '04_Family_Health': 'petry-household/kids/index.md',
+    '01_Household': 'household-vault/birmingham/index.md',
+    '02_Finance_Legal': 'household-vault/finances/index.md',
+    '03_Vehicles': 'household-vault/vehicles/index.md',
+    '04_Family_Health_School': 'household-vault/kids/index.md',
     '05_Tech_Infrastructure':
-      'petry-household/our-technology/digital-backups/index.md',
+      'household-vault/our-technology/digital-backups/index.md',
     '06_Work_Career': 'dp-work-notes/notes/index.md',
     '07_Community_NonProfit':
       'helpingoneguy/organization/organization/index.md',

src/gmail-ai-classifier/config.gs

@@ -1,18 +1,22 @@
 /**
  * Configuration schema for Gemini AI Semantic Email Classifier & Auto-Filter Engine
- * Supports Multi-Account Household Deployment (Option A)
+ * Supports Multi-Account Household Deployment (Option A: user@example.com & partner@example.com)
  */
 
 function getAiClassifierConfig() {
   var props = PropertiesService.getScriptProperties()
+  var activeUserEmail =
+    Session.getEffectiveUser().getEmail() ||
+    props.getProperty('USER_ACCOUNT_EMAIL') ||
+    'household-member@gmail.com'
+  var isDon = activeUserEmail.toLowerCase().indexOf('partner') !== -1
+  var partnerEmail = isDon ? 'user@example.com' : 'partner@example.com'
 
   return {
     geminiApiKey: props.getProperty('GEMINI_API_KEY') || '',
     githubToken: props.getProperty('GITHUB_PAT') || '',
-    userAccountEmail:
-      Session.getEffectiveUser().getEmail() ||
-      props.getProperty('USER_ACCOUNT_EMAIL') ||
-      'household-member@gmail.com',
+    userAccountEmail: activeUserEmail,
+    partnerEmail: partnerEmail,
     processedLabel: 'Processed',
     unprocessedQuery: 'in:inbox -label:Processed',
     autoFilterConfidenceThreshold: 0.95,
@@ -24,7 +28,7 @@ function getAiClassifierConfig() {
       '01_Household',
       '02_Finance_Legal',
       '03_Vehicles',
-      '04_Family_Health',
+      '04_Family_Health_School',
       '05_Tech_Infrastructure',
       '06_Work_Career',
       '07_Community_NonProfit',

src/gmail-ai-classifier/gitHubSync.gs

@@ -9,7 +9,7 @@
  * - Idempotency Guard (skips duplicate entries)
  */
 
-var GITHUB_REPO_OWNER = 'don-petry'
+var GITHUB_REPO_OWNER = 'user-org'
 var GITHUB_REPO_NAME = 'self-private'
 
 /**
@@ -98,7 +98,7 @@ function executeGitHubCommit(filePath, entryMd, commitMessage, githubToken) {
         topicTitle +
         '\ncreated: ' +
         Utilities.formatDate(new Date(), 'GMT', 'yyyy-MM-dd') +
-        '\nnotebook: petry-household\nsection: general\n---\n\n' +
+        '\nnotebook: household-vault\nsection: general\n---\n\n' +
         '# ' +
         topicTitle +
         '\n\n' +
@@ -219,11 +219,181 @@ function insertEntryIntoLogSection(fullContent, newEntry) {
   return fullContent + '\n' + newEntry
 }
 
+/**
+ * 2-Way Sync Engine: Fetches rules.json from self-private via GitHub REST API.
+ */
+function fetchRulesFromGitHub(filePath, githubToken) {
+  var targetPath =
+    filePath ||
+    '05_Tech_Infrastructure/gmail-cleanup-and-label-taxonomy/rules.json'
+  var token =
+    githubToken ||
+    PropertiesService.getScriptProperties().getProperty('GITHUB_PAT')
+  if (!token) {
+    console.log(
+      '[gitHubSync] GITHUB_PAT not set. Skipping fetchRulesFromGitHub.'
+    )
+    return null
+  }
+
+  var url =
+    'https://api.github.com/repos/' +
+    GITHUB_REPO_OWNER +
+    '/' +
+    GITHUB_REPO_NAME +
+    '/contents/' +
+    targetPath
+  var headers = {
+    Authorization: 'token ' + token,
+    Accept: 'application/vnd.github.v3+json',
+    'User-Agent': 'Google-Apps-Script',
+  }
+
+  try {
+    var res = UrlFetchApp.fetch(url, {
+      method: 'get',
+      headers: headers,
+      muteHttpExceptions: true,
+    })
+    if (res.getResponseCode() === 200) {
+      var data = JSON.parse(res.getContentText())
+      var decoded = Utilities.newBlob(
+        Utilities.base64Decode(data.content)
+      ).getDataAsString()
+      var parsed = JSON.parse(decoded)
+      parsed._sha = data.sha
+      return parsed
+    }
+  } catch (e) {
+    console.error(
+      '[gitHubSync] Exception fetching rules from GitHub:',
+      e.message
+    )
+  }
+  return null
+}
+
+/**
+ * 2-Way Sync Engine: Commits rules object back to self-private via GitHub REST API.
+ */
+function commitRulesToGitHub(rulesObj, commitMessage, githubToken) {
+  var targetPath =
+    '05_Tech_Infrastructure/gmail-cleanup-and-label-taxonomy/rules.json'
+  var token =
+    githubToken ||
+    PropertiesService.getScriptProperties().getProperty('GITHUB_PAT')
+  if (!token) {
+    console.log(
+      '[gitHubSync] GITHUB_PAT not set. Skipping commitRulesToGitHub.'
+    )
+    return false
+  }
+
+  var currentRemote = fetchRulesFromGitHub(targetPath, token)
+  var sha = currentRemote ? currentRemote._sha : null
+  delete rulesObj._sha
+  rulesObj.updatedAt = Utilities.formatDate(
+    new Date(),
+    'GMT',
+    "yyyy-MM-dd'T'HH:mm:ss'Z'"
+  )
+
+  var rawJson = JSON.stringify(rulesObj, null, 2)
+  var base64Content = Utilities.base64Encode(rawJson)
+
+  var url =
+    'https://api.github.com/repos/' +
+    GITHUB_REPO_OWNER +
+    '/' +
+    GITHUB_REPO_NAME +
+    '/contents/' +
+    targetPath
+  var headers = {
+    Authorization: 'token ' + token,
+    Accept: 'application/vnd.github.v3+json',
+    'User-Agent': 'Google-Apps-Script',
+  }
+
+  var payload = {
+    message:
+      commitMessage ||
+      'feat(taxonomy): update rules.json via 2-way Apps Script sync engine',
+    content: base64Content,
+    branch: 'main',
+  }
+  if (sha) payload.sha = sha
+
+  try {
+    var putRes = UrlFetchApp.fetch(url, {
+      method: 'put',
+      headers: headers,
+      contentType: 'application/json',
+      payload: JSON.stringify(payload),
+      muteHttpExceptions: true,
+    })
+    var status = putRes.getResponseCode()
+    return status === 200 || status === 201
+  } catch (e) {
+    console.error(
+      '[gitHubSync] Exception committing rules to GitHub:',
+      e.message
+    )
+    return false
+  }
+}
+
+/**
+ * Perform bi-directional 2-Way Synchronization between GAS Script Properties & GitHub rules.json.
+ */
+function syncTwoWayRules() {
+  var props = PropertiesService.getScriptProperties()
+  var remoteRules = fetchRulesFromGitHub()
+  if (!remoteRules) return false
+
+  var localJsonStr = props.getProperty('CLASSIFICATION_RULES_JSON')
+  if (!localJsonStr) {
+    // Initial GAS setup: Store remote rules locally
+    props.setProperty('CLASSIFICATION_RULES_JSON', JSON.stringify(remoteRules))
+    console.log('[gitHubSync] Local rules initialized from GitHub rules.json.')
+    return true
+  }
+
+  var localRules = JSON.parse(localJsonStr)
+  var remoteDate = new Date(remoteRules.updatedAt || 0).getTime()
+  var localDate = new Date(localRules.updatedAt || 0).getTime()
+
+  if (remoteDate > localDate) {
+    // GitHub rules are newer -> Update GAS Script Property
+    props.setProperty('CLASSIFICATION_RULES_JSON', JSON.stringify(remoteRules))
+    console.log(
+      '[gitHubSync] Pulled newer rules from GitHub into GAS Script Properties.'
+    )
+    return true
+  } else if (localDate > remoteDate) {
+    // GAS rules were tuned online -> Push back to GitHub
+    var success = commitRulesToGitHub(
+      localRules,
+      'feat(taxonomy): push live Apps Script rule tuning to GitHub rules.json'
+    )
+    if (success)
+      console.log(
+        '[gitHubSync] Pushed live GAS rule tuning to GitHub rules.json.'
+      )
+    return success
+  }
+
+  console.log('[gitHubSync] 2-Way Rules Sync is up-to-date.')
+  return true
+}
+
 if (typeof module !== 'undefined' && module.exports) {
   module.exports = {
     appendMarkdownEntryToGitHubRepo: appendMarkdownEntryToGitHubRepo,
     executeGitHubCommit: executeGitHubCommit,
     extractTopicTitleFromPath: extractTopicTitleFromPath,
     insertEntryIntoLogSection: insertEntryIntoLogSection,
+    fetchRulesFromGitHub: fetchRulesFromGitHub,
+    commitRulesToGitHub: commitRulesToGitHub,
+    syncTwoWayRules: syncTwoWayRules,
   }
 }