From 057c41fbbfbafa869d8f720051d02f3cd5c9edb3 Mon Sep 17 00:00:00 2001 From: NicolasVD Date: Fri, 25 Sep 2026 12:27:03 +0200 Subject: [PATCH 1/2] docs(i18n): translate governance specifications and QA test guides to english - Translate docs/scripts-reference.md operational and architectural guide to English (L-02) - Translate docs/qa-classification-test-guide.md test matrix and philosophy to English (L-04) - Translate docs/analytics-taxonomy.md event catalog and Zero-PII policies to English (L-02) Closes #10 --- docs/analytics-taxonomy.md | 134 ++++++++-------- docs/qa-classification-test-guide.md | 124 +++++++-------- docs/scripts-reference.md | 221 +++++++++++++-------------- 3 files changed, 232 insertions(+), 247 deletions(-) diff --git a/docs/analytics-taxonomy.md b/docs/analytics-taxonomy.md index df18459..24990aa 100644 --- a/docs/analytics-taxonomy.md +++ b/docs/analytics-taxonomy.md @@ -1,116 +1,116 @@ -# 📊 Taxonomie & ÉvĂ©nements Analytics (Zero-PII & Privacy-First) +# 📊 Analytics Taxonomy & Events (Zero-PII & Privacy-First) -Ce document formalise la structure, les Ă©vĂ©nements et les paramĂštres de tĂ©lĂ©mĂ©trie de **Agentic Android Kernel**. +This document formalizes the telemetry structure, event catalog, and parameters for the **Agentic Android Kernel**. --- -## đŸ›Ąïž 1. Principes de ConfidentialitĂ© & Éthique (Zero-PII) +## đŸ›Ąïž 1. Privacy Principles & Ethics (Zero-PII) -L'architecture de tĂ©lĂ©mĂ©trie de Agentic Android Kernel est conçue selon le principe strict du **Privacy by Design** : +The telemetry architecture of Agentic Android Kernel is designed under the strict principle of **Privacy by Design**: -1. **Aucune DonnĂ©e Personnelle Identifiable (Zero-PII)** : Les titres de tĂąches, descriptions, noms propres, adresses emails et contenus saisis par l'utilisateur ne sont **jamais** envoyĂ©s dans les Ă©vĂ©nements d'analytics. -2. **Bucketing / Plages de Valeurs** : Toutes les longueurs de texte et les nombres d'Ă©lĂ©ments sont regroupĂ©s en intervalles discrets (ex: `1-20`, `21-50`, `51-100`, `100+`) pour Ă©viter tout traçage indirect par empreinte textuelle. -3. **Comportement Hors-Ligne & Robuste** : Si Firebase Analytics n'est pas initialisĂ© ou en mode avion, le tracker encapsule les appels sans aucun crash ni blocage de l'UI (`FirebaseAnalyticsTracker`). +1. **Zero Personally Identifiable Information (Zero-PII)**: Task titles, descriptions, personal names, email addresses, and user-generated text are **never** transmitted in analytics events. +2. **Bucketing / Value Ranges**: All text lengths and item counts are grouped into discrete intervals (e.g., `1-20`, `21-50`, `51-100`, `100+`) to prevent indirect fingerprinting through textual cardinality. +3. **Robust & Offline Behavior**: If Firebase Analytics is uninitialized or in airplane mode, the tracker safely encapsulates calls without causing crashes or blocking the UI (`FirebaseAnalyticsTracker`). --- -## 📈 2. PropriĂ©tĂ©s Utilisateur (User Properties) +## 📈 2. User Properties -| ClĂ© | Type | Exemples de Valeurs | Description | +| Key | Type | Example Values | Description | |---|---|---|---| -| `access_state` | String | `guest`, `solo`, `duo` | État d'accĂšs actuel (InvitĂ©, ConnectĂ© Solo, JumelĂ© en Duo). | -| `theme_preference` | String | `light`, `dark`, `system` | PrĂ©fĂ©rence de thĂšme d'affichage. | -| `is_partner_linked` | Boolean | `true`, `false` | Indique si le compte est jumelĂ© Ă  un partenaire. | -| `active_loads_bucket` | String | `0`, `1-5`, `6-15`, `16-30`, `30+` | Tranche du nombre de charges mentales actives. | -| `focus_streak_bucket` | String | `0`, `1-3`, `4-7`, `8-14`, `15-30`, `30+` | SĂ©rie quotidienne de priorisation active. | +| `access_state` | String | `guest`, `solo`, `duo` | Current access state (Guest, Authenticated Solo, Paired Duo). | +| `theme_preference` | String | `light`, `dark`, `system` | Display theme preference. | +| `is_partner_linked` | Boolean | `true`, `false` | Indicates whether the account is paired with a partner. | +| `active_loads_bucket` | String | `0`, `1-5`, `6-15`, `16-30`, `30+` | Bucket of active mental load items. | +| `focus_streak_bucket` | String | `0`, `1-3`, `4-7`, `8-14`, `15-30`, `30+` | Daily active prioritization streak bucket. | --- -## đŸ·ïž 3. Catalogue des ÉvĂ©nements par Domaine Fonctionnel +## đŸ·ïž 3. Event Catalog by Functional Domain -### 🧠 A. Intelligence Artificielle & Classification Two-Tier (Issue #2) +### 🧠 A. Artificial Intelligence & Two-Tier Classification (Issue #2) -| Nom de l'ÉvĂ©nement | ParamĂštres | Description | +| Event Name | Parameters | Description | |---|---|---| -| `ai_classification_triggered` | `input_length_bucket` (String : `1-10`, `11-20`, `21-50`, `50+`)
`has_partner_context` (Boolean) | Déclenché lors de l'évaluation cognitive d'une tùche. | -| `ai_quadrant_suggested` | `source` (String : `heuristic`, `gemini_flash`)
`suggested_quadrant` (String : `do_today`, `schedule`, `delegate`, `park`)
`suggested_area` (String : `self`, `home`, `work`)
`confidence_bucket` (String : `high`, `medium`, `low`) | Émis lorsqu'une suggestion de quadrant et de domaine de vie est prĂ©sentĂ©e Ă  l'utilisateur. | -| `ai_quadrant_applied` | `quadrant` (String)
`area` (String)
`source` (String)
`time_to_apply_ms` (Long) | Enregistré lorsque l'utilisateur touche le chip de suggestion pour l'appliquer en 1-tap. | -| `ai_quadrant_dismissed` | `suggested_quadrant` (String)
`manual_selected_quadrant` (String)
`suggested_area` (String, opt)
`manual_selected_area` (String, opt) | Enregistré lorsque l'utilisateur ignore ou remplace la suggestion IA par un choix manuel. | +| `ai_classification_triggered` | `input_length_bucket` (String: `1-10`, `11-20`, `21-50`, `50+`)
`has_partner_context` (Boolean) | Triggered when evaluating cognitive workload for a task. | +| `ai_quadrant_suggested` | `source` (String: `heuristic`, `gemini_flash`)
`suggested_quadrant` (String: `do_today`, `schedule`, `delegate`, `park`)
`suggested_area` (String: `self`, `home`, `work`)
`confidence_bucket` (String: `high`, `medium`, `low`) | Emitted when a quadrant and life area suggestion is presented to the user. | +| `ai_quadrant_applied` | `quadrant` (String)
`area` (String)
`source` (String)
`time_to_apply_ms` (Long) | Recorded when the user taps the suggestion chip to apply it in 1-tap. | +| `ai_quadrant_dismissed` | `suggested_quadrant` (String)
`manual_selected_quadrant` (String)
`suggested_area` (String, opt)
`manual_selected_area` (String, opt) | Recorded when the user dismisses or overrides the AI suggestion with a manual selection. | --- -### 📝 B. Capture Rapide & Gestion des Charges Mentales +### 📝 B. Quick Capture & Mental Load Management -| Nom de l'ÉvĂ©nement | ParamĂštres | Description | +| Event Name | Parameters | Description | |---|---|---| -| `quick_capture_submitted` | `char_count_bucket` (String : `1-20`, `21-50`, `51-100`, `100+`)
`has_details` (Boolean) | Soumission d'une pensée depuis la barre d'accueil. | -| `mental_load_created` | `area` (String : `self`, `home`, `work`)
`quadrant` (String)
`is_shared` (Boolean)
`is_ai_assisted` (Boolean) | Création et sauvegarde d'une nouvelle charge mentale. | -| `mental_load_updated` | `area` (String)
`quadrant` (String)
`is_shared` (Boolean)
`changed_quadrant` (Boolean)
`changed_area` (Boolean) | Mise à jour des propriétés d'une tùche existante. | -| `mental_load_deleted` | `area` (String)
`quadrant` (String)
`was_completed` (Boolean)
`was_shared` (Boolean) | Suppression d'une charge mentale. | -| `task_completed` | `area` (String)
`quadrant` (String)
`is_shared` (Boolean)
`is_voted_today` (Boolean) | Coche / complétion d'une tùche. | -| `task_reopened` | `area` (String)
`quadrant` (String)
`is_shared` (Boolean) | Réouverture d'une tùche terminée. | -| `task_filter_applied` | `filter_mode` (String : `all`, `shared`, `personal`, `top3`)
`results_count` (Int) | Application d'un filtre sur la liste des charges. | +| `quick_capture_submitted` | `char_count_bucket` (String: `1-20`, `21-50`, `51-100`, `100+`)
`has_details` (Boolean) | Submitting a thought from the home capture bar. | +| `mental_load_created` | `area` (String: `self`, `home`, `work`)
`quadrant` (String)
`is_shared` (Boolean)
`is_ai_assisted` (Boolean) | Creating and saving a new mental load item. | +| `mental_load_updated` | `area` (String)
`quadrant` (String)
`is_shared` (Boolean)
`changed_quadrant` (Boolean)
`changed_area` (Boolean) | Updating properties of an existing task. | +| `mental_load_deleted` | `area` (String)
`quadrant` (String)
`was_completed` (Boolean)
`was_shared` (Boolean) | Deleting a mental load item. | +| `task_completed` | `area` (String)
`quadrant` (String)
`is_shared` (Boolean)
`is_voted_today` (Boolean) | Checking / completing a task. | +| `task_reopened` | `area` (String)
`quadrant` (String)
`is_shared` (Boolean) | Reopening a completed task. | +| `task_filter_applied` | `filter_mode` (String: `all`, `shared`, `personal`, `top3`)
`results_count` (Int) | Applying a filter on the task list. | --- -### 🧭 C. Matrice d'Eisenhower & Priorisation Quotidienne +### 🧭 C. Eisenhower Matrix & Daily Prioritization -| Nom de l'ÉvĂ©nement | ParamĂštres | Description | +| Event Name | Parameters | Description | |---|---|---| -| `daily_vote_toggled` | `action` (String : `added`, `removed`)
`current_voted_count` (Int : `1` Ă  `3`)
`area` (String)
`quadrant` (String) | Ajout ou retrait d'une tĂąche dans le Top 3 quotidien. | -| `daily_vote_limit_reached` | `max_votes` (Int : `3`)
`active_loads_count` (Int) | Tentative de dépassement de la limite de 3 votes. | -| `daily_votes_reset` | `previous_voted_count` (Int) | Réinitialisation quotidienne des votes Top 3. | -| `quadrant_reassigned` | `previous_quadrant` (String, opt)
`target_quadrant` (String)
`area` (String) | DĂ©placement direct d'une tĂąche vers un autre quadrant. | +| `daily_vote_toggled` | `action` (String: `added`, `removed`)
`current_voted_count` (Int: `1` to `3`)
`area` (String)
`quadrant` (String) | Adding or removing a task from the daily Top 3. | +| `daily_vote_limit_reached` | `max_votes` (Int: `3`)
`active_loads_count` (Int) | Attempting to exceed the 3-vote daily limit. | +| `daily_votes_reset` | `previous_voted_count` (Int) | Daily reset of Top 3 votes. | +| `quadrant_reassigned` | `previous_quadrant` (String, opt)
`target_quadrant` (String)
`area` (String) | Direct reassignment of a task to another quadrant. | --- -### đŸ‘« D. Espace Duo & Jumelage Partenaire +### đŸ‘« D. Duo Space & Partner Pairing -| Nom de l'ÉvĂ©nement | ParamĂštres | Description | +| Event Name | Parameters | Description | |---|---|---| -| `partner_invite_generated` | `is_regenerated` (Boolean) | GĂ©nĂ©ration d'un code sanctuaire `SANCTUARY-XXXXXX`. | -| `partner_join_attempted` | `code_format_valid` (Boolean) | Soumission d'un code d'invitation partenaire. | -| `partner_paired_success` | `method` (String : `sanctuary_code`) | Jumelage rĂ©ussi des deux profils. | -| `partner_paired_failed` | `error_reason` (String) | Échec de jumelage (code invalide, dĂ©jĂ  liĂ©). | -| `partner_unpaired` | `active_tasks_count` (Int) | Dissociation du partenaire. | -| `partner_upvote_toggled` | `action` (String)
`area` (String)
`is_completed` (Boolean) | Vote de soutien/priorité sur une tùche partagée. | -| `partner_ledger_viewed` | `active_dimension` (String)
`total_shared_tasks` (Int) | Consultation du Grand Livre de synergie. | -| `partner_ledger_dim_changed`| `selected_dimension` (String : `active`, `initiated`, `resolved`)
`user_percentage` (Int)
`partner_percentage` (Int) | Bascule entre les 3 dimensions de charge du couple. | -| `couple_synergy_viewed` | `focus_streak_days` (Int)
`total_completed_shared` (Int) | Ouverture de la modale de célébration de couple. | -| `shared_privacy_updated` | `privacy_mode` (String) | Modification de la visibilité des tùches partagées. | +| `partner_invite_generated` | `is_regenerated` (Boolean) | Generating a sanctuary code `SANCTUARY-XXXXXX`. | +| `partner_join_attempted` | `code_format_valid` (Boolean) | Submitting a partner invitation code. | +| `partner_paired_success` | `method` (String: `sanctuary_code`) | Successful pairing of both profiles. | +| `partner_paired_failed` | `error_reason` (String) | Pairing failure (invalid code, already linked). | +| `partner_unpaired` | `active_tasks_count` (Int) | Unpairing from partner. | +| `partner_upvote_toggled` | `action` (String)
`area` (String)
`is_completed` (Boolean) | Support/priority vote on a shared task. | +| `partner_ledger_viewed` | `active_dimension` (String)
`total_shared_tasks` (Int) | Viewing the Synergy Ledger. | +| `partner_ledger_dim_changed`| `selected_dimension` (String: `active`, `initiated`, `resolved`)
`user_percentage` (Int)
`partner_percentage` (Int) | Switching between the 3 couple workload dimensions. | +| `couple_synergy_viewed` | `focus_streak_days` (Int)
`total_completed_shared` (Int) | Opening the couple synergy celebration modal. | +| `shared_privacy_updated` | `privacy_mode` (String) | Updating shared tasks visibility mode. | --- -### 🔐 E. Authentification, Soft-Gating & ParamĂštres +### 🔐 E. Authentication, Soft-Gating & Settings -| Nom de l'ÉvĂ©nement | ParamĂštres | Description | +| Event Name | Parameters | Description | |---|---|---| -| `screen_view` | `screen_name` (String)
`screen_class` (String)
`access_state` (String)
`active_loads_count` (Int)
`voted_loads_count` (Int) | Navigation vers un écran. | -| `sign_in_started` | `source` (String) | Déclenchement de la connexion Google. | -| `sign_in_success` | *(aucun)* | Connexion réussie. | -| `sign_in_failed` | `error_type` (String)
`error_message` (String) | Échec de connexion Google. | -| `sign_out` | `previous_access_state` (String) | DĂ©connexion volontaire de l'utilisateur. | -| `soft_gate_shown` | `trigger_feature` (String) | Affichage de la boĂźte de dialogue invitant Ă  la connexion/jumelage. | -| `theme_changed` | `new_theme` (String)
`previous_theme` (String, opt) | Changement du mode de thÚme (Clair / Sombre / SystÚme). | -| `gentle_reset_started` | `source` (String) | Lancement de la respiration guidée 4-4-4. | -| `gentle_reset_completed` | `duration_seconds` (Int : `30`)
`current_streak` (Int) | Complétion d'une session de recentrage zen. | +| `screen_view` | `screen_name` (String)
`screen_class` (String)
`access_state` (String)
`active_loads_count` (Int)
`voted_loads_count` (Int) | Navigating to a screen. | +| `sign_in_started` | `source` (String) | Initiating Google Sign-In. | +| `sign_in_success` | *(none)* | Successful sign-in. | +| `sign_in_failed` | `error_type` (String)
`error_message` (String) | Google Sign-In failure. | +| `sign_out` | `previous_access_state` (String) | Voluntary user sign-out. | +| `soft_gate_shown` | `trigger_feature` (String) | Displaying sign-in/pairing soft-gate modal. | +| `theme_changed` | `new_theme` (String)
`previous_theme` (String, opt) | Changing theme mode (Light / Dark / System). | +| `gentle_reset_started` | `source` (String) | Launching 4-4-4 guided breathing session. | +| `gentle_reset_completed` | `duration_seconds` (Int: `30`)
`current_streak` (Int) | Completing a zen centering session. | --- -### 🔁 F. RĂ©currence, ÉchĂ©ances & Rotation AlternĂ©e Duo (Issue #1) +### 🔁 F. Recurrence, Due Dates & Alternating Duo Rotation (Issue #1) -| Nom de l'ÉvĂ©nement | ParamĂštres | Description | +| Event Name | Parameters | Description | |---|---|---| -| `task_due_date_set` | `is_preset` (Boolean)
`preset_type` (String, opt : `today`, `tomorrow`, `weekend`, `next_week`)
`is_recurring` (Boolean)
`days_until_due` (Int, opt) | Définition ou sélection rapide d'une échéance temporelle sur une charge mentale. | -| `recurring_task_created` | `frequency` (String : `daily`, `weekdays_only`, `weekends_only`, `weekly`, `biweekly`, `monthly`, `yearly`)
`is_duo_rotating` (Boolean)
`has_due_date` (Boolean)
`area` (String) | Création d'une tùche récurrente ou périodique. | -| `recurring_task_completed` | `frequency` (String)
`cycle_count` (Int)
`is_duo_rotating` (Boolean)
`has_due_date` (Boolean) | Complétion d'un cycle de tùche récurrente et déclenchement automatique du cycle suivant. | -| `duo_rotation_assigned` | `frequency` (String)
`cycle_count` (Int)
`next_assignee_role` (String : `partner`, `self`)
`days_to_next_due` (Int, opt) | Alternance automatique du responsable de la tĂąche pour le cycle suivant. | +| `task_due_date_set` | `is_preset` (Boolean)
`preset_type` (String, opt: `today`, `tomorrow`, `weekend`, `next_week`)
`is_recurring` (Boolean)
`days_until_due` (Int, opt) | Setting or quick-selecting a due date on a mental load item. | +| `recurring_task_created` | `frequency` (String: `daily`, `weekdays_only`, `weekends_only`, `weekly`, `biweekly`, `monthly`, `yearly`)
`is_duo_rotating` (Boolean)
`has_due_date` (Boolean)
`area` (String) | Creating a recurring or periodic task. | +| `recurring_task_completed` | `frequency` (String)
`cycle_count` (Int)
`is_duo_rotating` (Boolean)
`has_due_date` (Boolean) | Completing a recurring task cycle and triggering the next cycle. | +| `duo_rotation_assigned` | `frequency` (String)
`cycle_count` (Int)
`next_assignee_role` (String: `partner`, `self`)
`days_to_next_due` (Int, opt) | Automatic alternation of task assignee for the next cycle. | --- -## đŸ§Ș 4. Validation & Tests AutomatisĂ©s +## đŸ§Ș 4. Validation & Automated Tests -Tous les Ă©vĂ©nements et leurs sĂ©rialisations de paramĂštres sont validĂ©s dans les tests unitaires : +All events and parameter serializations are validated in unit tests: ```bash ./gradlew testDebugUnitTest --tests com.secondbrain.app.data.analytics.AnalyticsTrackerTest diff --git a/docs/qa-classification-test-guide.md b/docs/qa-classification-test-guide.md index 495f6c9..62c8828 100644 --- a/docs/qa-classification-test-guide.md +++ b/docs/qa-classification-test-guide.md @@ -1,116 +1,116 @@ -# 🧠 Guide de Test & RĂ©fĂ©rentiel de Classification IA (Matrice de ClartĂ© & Domaines de Vie) +# 🧠 QA Test Guide & AI Classification Reference (Clarity Matrix & Areas of Life) -Ce document dĂ©taille la philosophie de gestion cognitive de **Agentic Android Kernel**, le comportement du moteur hybride **Two-Tier (Heuristique locale + Gemini Flash-Lite)**, ainsi que la **matrice de test exhaustive (les 12 combinaisons)** pour valider les suggestions de quadrants et de domaines de vie. +This document details the cognitive management philosophy of **Agentic Android Kernel**, the behavior of the **Two-Tier hybrid classification engine (Local Heuristic + Gemini Flash-Lite)**, and the **exhaustive test matrix (all 12 combinations)** used to validate quadrant and life area suggestions. --- -## 🌿 1. Philosophie & Vocabulaire Émotionnel Positif +## 🌿 1. Philosophy & Positive Emotional Vocabulary -Agentic Android Kernel applique les principes de la **Matrice d'Eisenhower** et de la mĂ©thode **GTD (Getting Things Done)**, rĂ©interprĂ©tĂ©s Ă  travers une approche apaisante (*Serene UX*) : +Agentic Android Kernel applies principles from the **Eisenhower Matrix** and the **GTD (Getting Things Done)** methodology, reinterpreted through a calming approach (*Serene UX*): -* **ZĂ©ro Stress / Non-injonction** : L'interface Ă©vite les termes anxiogĂšnes. -* **Entraide Duo** : Le terme traditionnel *"DĂ©lĂ©guer"* est remplacĂ© par **« Entraide Duo »** et **« À proposer au partenaire »** (*Duo Teamwork / Propose to partner*), valorisant l'interdĂ©pendance positive et l'allĂšgement partagĂ© de la charge mentale. -* **Sanctuaire Mental** : Le quadrant *"Éliminer / Ne pas faire"* est remplacĂ© par **« DĂ©poser au Sanctuaire »** (*Park in Sanctuary*), permettant de consigner une idĂ©e prĂ©cieuse sans s'imposer d'Ă©chĂ©ance ni culpabilitĂ©. +* **Zero Stress / Non-prescriptive**: The interface avoids anxiety-inducing terminology. +* **Duo Teamwork**: The traditional *"Delegate"* label is replaced by **"Duo Teamwork"** and **"Propose to partner"**, emphasizing positive interdependence and shared mental load reduction. +* **Mental Sanctuary**: The *"Eliminate / Won't do"* quadrant is replaced by **"Park in Sanctuary"**, providing a space to capture valuable thoughts without deadlines or guilt. --- -## 🧭 2. Les 4 Quadrants de la Matrice de ClartĂ© +## 🧭 2. The 4 Clarity Matrix Quadrants ``` - URGENT (Court Terme) NON-URGENT (Long Terme) + URGENT (Short Term) NON-URGENT (Long Term) ┌───────────────────────────────────┬───────────────────────────────────┐ - │ ⚡ À FAIRE AUJOURD'HUI │ 🌿 PLANIFIER & ALIGNER │ - IMPORTANT │ ‱ Haute urgence & Fort impact │ ‱ Fort impact, sĂ©rĂ©nitĂ© │ - (Haute Valeur) │ ‱ ÉchĂ©ance imminente (ce soir) │ ‱ Projets structurants, Self-care│ + │ ⚡ DO TODAY │ 🌿 SCHEDULE & ALIGN │ + IMPORTANT │ ‱ High urgency & high impact │ ‱ High impact, serene execution │ + (High Value) │ ‱ Imminent deadline (tonight) │ ‱ Structuring projects, Self-care│ ├───────────────────────────────────┌──────────────────────────────────── - │ đŸ€ ENTRAIDE DUO │ 🍃 DÉPOSER AU SANCTUAIRE │ - NON-IMPORTANT │ ‱ Urgent, faible complexitĂ© │ ‱ Faible urgence & faible impact │ -(Faible Charge) │ ‱ À proposer au partenaire │ ‱ IdĂ©e pour plus tard, Wishlist │ + │ đŸ€ DUO TEAMWORK │ 🍃 PARK IN SANCTUARY │ + NON-IMPORTANT │ ‱ Urgent, low complexity │ ‱ Low urgency & low impact │ + (Low Load) │ ‱ Propose to partner │ ‱ Someday-maybe, Wishlist │ └───────────────────────────────────┮───────────────────────────────────┘ ``` -### 🔍 Focus : "Planifier & Aligner" vs "DĂ©poser au Sanctuaire" +### 🔍 Focus: "Schedule & Align" vs. "Park in Sanctuary" -Une distinction fondamentale existe entre ces deux catĂ©gories : +A fundamental distinction exists between these two categories: -1. **🌿 Planifier & Aligner (`SCHEDULE` - Quadrant II)** : - * C'est le **« Quadrant d'or »** de l'efficacitĂ© et de la sĂ©rĂ©nitĂ©. - * Il regroupe les actions fondamentales qui mĂ©ritent une attention dĂ©libĂ©rĂ©e mais sans panique : bilans de santĂ©, intentions de vie, roadmap stratĂ©gique et **self-care actif**. - * 👉 *Exemple :* **« Prendre du temps pour moi »** ou **« Prendre rendez-vous mĂ©decin »** sont classĂ©s ici car prendre soin de son Ă©quilibre est une intention **importante** qui doit ĂȘtre planifiĂ©e calmement. +1. **🌿 Schedule & Align (`SCHEDULE` - Quadrant II)**: + * This is the **"Golden Quadrant"** of calm efficiency. + * It gathers essential actions deserving deliberate attention without panic: medical checkups, life intentions, strategic roadmaps, and **active self-care**. + * 👉 *Example:* **"Take time for myself"** or **"Book doctor checkup"** are classified here because personal balance is an **important** intention that should be planned calmly. -2. **🍃 DĂ©poser au Sanctuaire (`PARK` - Quadrant IV / Someday-Maybe)** : - * C'est l'espace pour **libĂ©rer son esprit** des pensĂ©es sans engagement immĂ©diat. - * Il accueille les envies d'exploration, curiositĂ©s, wishlists ou projets lointains qu'on veut stocker en lieu sĂ»r sans encombrer son champ attentionnel du moment. - * 👉 *Exemple :* **« IdĂ©e pour plus tard : tester le yoga aĂ©rien un jour »** ou **« Un jour apprendre Ă  jouer du piano »**. +2. **🍃 Park in Sanctuary (`PARK` - Quadrant IV / Someday-Maybe)**: + * A dedicated space to **free the mind** from commitments with zero immediate urgency. + * It welcomes exploratory curiosities, wishlists, and distant ambitions stored safely without cluttering current attention. + * 👉 *Example:* **"Idea for later: try aerial yoga someday"** or **"Someday learn how to play piano"**. --- -## đŸ·ïž 3. Les 3 Domaines de Vie (Areas of Life) +## đŸ·ïž 3. The 3 Areas of Life -1. **🧘 Pour Soi (`SELF`)** : SantĂ©, mĂ©decine prĂ©ventive, forme physique, sommeil, mĂ©ditation, bien-ĂȘtre, loisirs personnels et dĂ©connexion. -2. **🏡 Maison (`HOME`)** : Logement, entretien intĂ©rieur/extĂ©rieur, jardinage, bricolage, courses, repas, animaux de compagnie, enfants et logistique familiale. -3. **đŸ’Œ Travail (`WORK`)** : ActivitĂ© professionnelle, gestion de projets, rĂ©unions, fiscalitĂ©/comptabilitĂ©, clients, devis, contrats et stratĂ©gie. +1. **🧘 For Self (`SELF`)**: Health, preventive medicine, physical fitness, sleep, meditation, well-being, personal hobbies, and disconnecting. +2. **🏡 Home (`HOME`)**: Housing, indoor/outdoor maintenance, gardening, repairs, groceries, meals, pets, kids, and family logistics. +3. **đŸ’Œ Work (`WORK`)**: Professional activities, project management, meetings, taxes/accounting, clients, quotes, contracts, and strategy. --- -## ⚡ 4. Architecture Hybride Two-Tier +## ⚡ 4. Two-Tier Hybrid Architecture -1. **Tier 1 — Heuristique Locale (`< 5ms`)** : - * Analyse dĂ©terministe synchrone instantanĂ©e avec 0 ms de latence rĂ©seau. - * Tokenisation Unicode stricte (`\p{L}`) pour gĂ©rer nativement les accents français (*impĂŽts*, *santĂ©*, *mĂ©decin*) sans faux positifs sur les sous-chaĂźnes. - * SuggĂšre immĂ©diatement le Quadrant et le Domaine de Vie. +1. **Tier 1 — Local Heuristics (`< 5ms`)**: + * Instant synchronous deterministic analysis with 0 ms network latency. + * Strict Unicode tokenization (`\p{L}`) natively handling accented characters without substring false positives. + * Immediately suggests the Quadrant and Area of Life. -2. **Tier 2 — Gemini 3.5 Flash-Lite via Firebase AI Logic (Asynchrone)** : - * DĂ©clenchĂ© aprĂšs une pause de frappe (debounce de 400ms) ou Ă  la perte de focus. - * Utilise le modĂšle `gemini-3.5-flash-lite` via `com.google.firebase:firebase-ai` avec App Check (Play Integrity en production, `DebugAppCheckProvider` sur Ă©mulateur). - * Évalue la complexitĂ© cognitive, affine le domaine de vie (`HOME`, `WORK`, `SELF`), enrichit l'explication bienveillante (*rationale*) et ajuste la confiance. - * **RĂ©silience App Check Émulateur** : Si le jeton de debug n'est pas whitelistĂ© en environnement local, l'erreur 403 est interceptĂ©e sans polluer Crashlytics, et le Tier 1 heuristique garantit une classification instantanĂ©e et ininterrompue. +2. **Tier 2 — Gemini 3.5 Flash-Lite via Firebase AI Logic (Asynchronous)**: + * Triggered after typing stops (400ms debounce) or on focus loss. + * Uses `gemini-3.5-flash-lite` via `com.google.firebase:firebase-ai` with App Check (Play Integrity in production, `DebugAppCheckProvider` on emulator). + * Evaluates cognitive complexity, refines life area (`HOME`, `WORK`, `SELF`), enriches benevolent rationale, and tunes confidence. + * **Emulator App Check Resilience**: If debug tokens are not whitelisted in local environments, 403 errors are caught without polluting Crashlytics, and Tier 1 heuristics guarantee uninterrupted, instant classification. --- -## 📋 5. Matrice de Test ComplĂšte (Les 12 Combinaisons) +## 📋 5. Complete Test Matrix (All 12 Combinations) -Ce tableau fournit les phrases de test canoniques pour valider les 12 combinaisons possibles dans l'interface de saisie (`AddMentalLoadScreen.kt` et `EditMentalLoadSheet.kt`). +This table provides the canonical test phrases used to validate all 12 combinations in the input interface (`AddMentalLoadScreen.kt` and `EditMentalLoadSheet.kt`). -### 🧘 Domaines : Pour Soi (`SELF`) +### 🧘 Area: For Self (`SELF`) -| # | Quadrant Attendu | Phrase de Test Ă  Copier-Coller | DĂ©clencheurs / Justification | +| # | Expected Quadrant | Test Phrase (Copy-Paste) | Triggers / Rationale | |:---:|---|---|---| -| **1** | ⚡ **À Faire Aujourd'hui** | `Prendre mes antibiotiques et appeler mĂ©decin en urgence aujourd'hui` | `urgence`, `aujourd'hui` + `santĂ©`, `mĂ©decin` | -| **2** | 🌿 **Planifier & Aligner** | `Prendre rendez-vous bilan de santĂ© mĂ©decin` *(ou `Prendre du temps pour moi`)* | `santĂ©`, `mĂ©decin`, `rdv`, `temps pour moi` (sans marqueur d'urgence) | -| **3** | đŸ€ **Entraide Duo** | `Demander Ă  Sam de passer Ă  la pharmacie chercher mon ordonnance` | `demander Ă  Sam` + `pharmacie`, `ordonnance` | -| **4** | 🍃 **DĂ©poser au Sanctuaire** | `IdĂ©e pour plus tard : tester le yoga aĂ©rien un jour` | `idĂ©e pour plus tard`, `un jour` + `yoga` | +| **1** | ⚡ **Do Today** | `Prendre mes antibiotiques et appeler mĂ©decin en urgence aujourd'hui` | `urgence`, `aujourd'hui` + `santĂ©`, `mĂ©decin` | +| **2** | 🌿 **Schedule & Align** | `Prendre rendez-vous bilan de santĂ© mĂ©decin` *(or `Prendre du temps pour moi`)* | `santĂ©`, `mĂ©decin`, `rdv`, `temps pour moi` (no urgency marker) | +| **3** | đŸ€ **Duo Teamwork** | `Demander Ă  Sam de passer Ă  la pharmacie chercher mon ordonnance` | `demander Ă  Sam` + `pharmacie`, `ordonnance` | +| **4** | 🍃 **Park in Sanctuary** | `IdĂ©e pour plus tard : tester le yoga aĂ©rien un jour` | `idĂ©e pour plus tard`, `un jour` + `yoga` | --- -### 🏡 Domaines : Maison (`HOME`) +### 🏡 Area: Home (`HOME`) -| # | Quadrant Attendu | Phrase de Test Ă  Copier-Coller | DĂ©clencheurs / Justification | +| # | Expected Quadrant | Test Phrase (Copy-Paste) | Triggers / Rationale | |:---:|---|---|---| -| **5** | ⚡ **À Faire Aujourd'hui** | `Sortir les poubelles et rĂ©parer la fuite d'eau ce soir urgent` | `urgent`, `ce soir` + `poubelles`, `fuite`, `eau` | -| **6** | 🌿 **Planifier & Aligner** | `Tailler la haie et tondre la pelouse ce week-end` | `tailler`, `haie`, `tondre`, `pelouse` | -| **7** | đŸ€ **Entraide Duo** | `Demander Ă  Sam de faire les courses et acheter du lait` | `demander Ă  Sam` + `courses`, `lait` | -| **8** | 🍃 **DĂ©poser au Sanctuaire** | `IdĂ©e pour plus tard : crĂ©er un potager dans le jardin` | `idĂ©e pour plus tard` + `jardin`, `potager` | +| **5** | ⚡ **Do Today** | `Sortir les poubelles et rĂ©parer la fuite d'eau ce soir urgent` | `urgent`, `ce soir` + `poubelles`, `fuite`, `eau` | +| **6** | 🌿 **Schedule & Align** | `Tailler la haie et tondre la pelouse ce week-end` | `tailler`, `haie`, `tondre`, `pelouse` | +| **7** | đŸ€ **Duo Teamwork** | `Demander Ă  Sam de faire les courses et acheter du lait` | `demander Ă  Sam` + `courses`, `lait` | +| **8** | 🍃 **Park in Sanctuary** | `IdĂ©e pour plus tard : crĂ©er un potager dans le jardin` | `idĂ©e pour plus tard` + `jardin`, `potager` | --- -### đŸ’Œ Domaines : Travail (`WORK`) +### đŸ’Œ Area: Work (`WORK`) -| # | Quadrant Attendu | Phrase de Test Ă  Copier-Coller | DĂ©clencheurs / Justification | +| # | Expected Quadrant | Test Phrase (Copy-Paste) | Triggers / Rationale | |:---:|---|---|---| -| **9** | ⚡ **À Faire Aujourd'hui** | `DĂ©claration impĂŽts urgente aujourd'hui avant 18h` | `urgente`, `aujourd'hui`, `avant 18h` + `impĂŽts`, `dĂ©claration` | -| **10** | 🌿 **Planifier & Aligner** | `PrĂ©parer la roadmap stratĂ©gique du projet Q4` | `roadmap`, `stratĂ©gique`, `projet`, `q4` | -| **11** | đŸ€ **Entraide Duo** | `Demander Ă  Sam de relire le devis et le contrat` | `demander Ă  Sam` + `devis`, `contrat` | -| **12** | 🍃 **DĂ©poser au Sanctuaire** | `IdĂ©e pour plus tard : explorer un projet open source un jour` | `idĂ©e pour plus tard`, `explorer`, `un jour` + `projet` | +| **9** | ⚡ **Do Today** | `DĂ©claration impĂŽts urgente aujourd'hui avant 18h` | `urgente`, `aujourd'hui`, `avant 18h` + `impĂŽts`, `dĂ©claration` | +| **10** | 🌿 **Schedule & Align** | `PrĂ©parer la roadmap stratĂ©gique du projet Q4` | `roadmap`, `stratĂ©gique`, `projet`, `q4` | +| **11** | đŸ€ **Duo Teamwork** | `Demander Ă  Sam de relire le devis et le contrat` | `demander Ă  Sam` + `devis`, `contrat` | +| **12** | 🍃 **Park in Sanctuary** | `IdĂ©e pour plus tard : explorer un projet open source un jour` | `idĂ©e pour plus tard`, `explorer`, `un jour` + `projet` | --- -## đŸ§Ș 6. VĂ©rification AutomatisĂ©e +## đŸ§Ș 6. Automated Verification -La suite de tests unitaires valide l'intĂ©gralitĂ© de ces rĂšgles : +The unit test suite validates all of these rules: ```bash ./gradlew testDebugUnitTest --tests com.secondbrain.app.data.classifier.HeuristicTaskClassifierTest ``` -Test validĂ© : `verify all 12 combinations of AreaOfLife and PriorityQuadrant` dans `HeuristicTaskClassifierTest.kt`. +Validated test: `verify all 12 combinations of AreaOfLife and PriorityQuadrant` in `HeuristicTaskClassifierTest.kt`. diff --git a/docs/scripts-reference.md b/docs/scripts-reference.md index 55a943d..9465973 100644 --- a/docs/scripts-reference.md +++ b/docs/scripts-reference.md @@ -6,41 +6,40 @@ --- -## 1. Vision & Architecture : Scripts Atomiques & Composition par CompĂ©tences SĂ©mantiques +## 1. Vision & Architecture: Atomic Scripts & Semantic Skills Composition -Le projet **Agentic Android Kernel** adopte une architecture d'automatisation stricte basĂ©e sur le principe de **responsabilitĂ© unique (SRP)** : +The **Agentic Android Kernel** project enforces a strict automation architecture rooted in the **Single Responsibility Principle (SRP)**: -1. **Scripts Atomiques (Single Responsibility)** : - Chaque script dans `scripts/` remplit une **unique fonction dĂ©terministe** (ex: valider les contrats documentaires, exĂ©cuter les tests de compilation Android, vĂ©rifier les rĂšgles Firestore, ou tĂ©lĂ©verser les captures sur Stitch). -2. **Composition par CompĂ©tences SĂ©mantiques & Pipelines (Orchestration)** : - Les enchaĂźnements complexes de tĂąches ne sont pas codĂ©s en dur dans de gros scripts monolithiques, mais orchestrĂ©s via : - - Les **CompĂ©tences SĂ©mantiques de l'Agent** ([`.agent/skills/`](../.agent/skills/)) pilotĂ©es par intentions et commandes (`plan-issue`, `open-pr`, `quality-airbag`, `distribute-local`, `sync-stitch`, `triage-feedback`). - - Les **Pipelines CI/CD GitHub Actions** ([`.github/workflows/`](../.github/workflows/)) (`delivery-pipeline.yml`). +1. **Atomic Scripts (Single Responsibility)**: + Every script under `scripts/` fulfills a **single deterministic function** (e.g., validating documentation contracts, running Android build sanity checks, testing runtime security guardrails, or uploading screenshots to Stitch). +2. **Composition via Semantic Skills & Pipelines (Orchestration)**: + Complex multi-step workflows are not hardcoded into brittle monolithic scripts, but orchestrated via: + - **Agent Semantic Skills** ([`.agent/skills/`](../.agent/skills/)) driven by user intents and slash commands (`plan-issue`, `open-pr`, `quality-airbag`, `distribute-local`, `sync-stitch`, `triage-feedback`). + - **GitHub Actions CI/CD Pipelines** ([`.github/workflows/`](../.github/workflows/)) (`delivery-pipeline.yml`). ```mermaid graph TD - subgraph SkillsPipelines ["Orchestrateurs (Skills / Pipelines)"] + subgraph SkillsPipelines ["Orchestrators (Skills / Pipelines)"] WF_QC["quality-airbag (/quality-check)"] WF_DIST["/distribute-local"] WF_STITCH["/sync-stitch"] CI_DELIVERY["Delivery Pipeline & Quality Gate (delivery-pipeline.yml)"] end - subgraph AtomicScripts ["Scripts Atomiques (scripts/)"] + subgraph AtomicScripts ["Atomic Scripts (scripts/)"] S_VAL["validate-docs.sh"] S_QC["quality-check.sh"] - S_RULES["test-firestore-rules.mjs"] - S_DEPLOY["deploy-firestore-rules.mjs"] + S_GUARD["test-runtime-guardrails.mjs"] + S_HOOKS["install-hooks.sh"] S_DIST["deploy-app-distribution.sh"] S_GEN["generate-screenshots.sh"] S_STITCH["upload-screenshots.py"] - S_CLEAN["cleanup-e2e-firestore.mjs"] S_IDE["inspect-ide.sh"] end WF_QC --> S_VAL WF_QC --> S_QC - WF_QC --> S_RULES + WF_QC --> S_GUARD WF_STITCH --> S_VAL WF_STITCH --> S_GEN @@ -51,130 +50,128 @@ graph TD CI_DELIVERY --> S_VAL CI_DELIVERY --> S_QC - CI_DELIVERY --> S_RULES + CI_DELIVERY --> S_GUARD ``` --- -## 2. RĂ©pertoire Complet des Scripts +## 2. Complete Scripts Directory -| Fichier Script | Langage | Nature | ResponsabilitĂ© Unique | DĂ©clencheurs / Skills | +| Script File | Language | Nature | Single Responsibility | Triggers / Skills | |---|---|---|---|---| -| [`scripts/validate-docs.sh`](../scripts/validate-docs.sh) | Bash | Atomique | Valide l'intĂ©gritĂ© et la conformitĂ© des contrats documentaires (`DESIGN.md`, `design-system.md`, `agent.md`, playbooks, skills, rĂšgles). | `quality-airbag`, `sync-stitch`, `delivery-pipeline.yml` | -| [`scripts/quality-check.sh`](../scripts/quality-check.sh) | Bash | Atomique | ExĂ©cute la suite Gradle complĂšte de compilation Kotlin/Java, Lint Android Debug/Release, et tests unitaires/Robolectric. | `quality-airbag`, `open-pr`, `delivery-pipeline.yml` | -| [`scripts/test-firestore-rules.mjs`](../scripts/test-firestore-rules.mjs) | Node.js (ESM) | Atomique | Teste localement `firestore.rules` contre 16 assertions de sĂ©curitĂ© (moindre privilĂšge, isolation couple, absence d'escalade). | `quality-airbag`, CI, Debug Screen | -| [`scripts/deploy-firestore-rules.mjs`](../scripts/deploy-firestore-rules.mjs) | Node.js (ESM) | Atomique | DĂ©ploie et publie `firestore.rules` directement sur Google Cloud / Firebase via l'API REST avec JWT compte de service. | DĂ©ploiement manuel sĂ©curisĂ© | -| [`scripts/deploy-app-distribution.sh`](../scripts/deploy-app-distribution.sh) | Bash | Atomique | Compile l'APK et l'envoie sur Firebase App Distribution avec calcul automatique de version et notes formatĂ©es. | `distribute-local`, DĂ©ploiement testeurs ad-hoc | -| [`scripts/generate-screenshots.sh`](../scripts/generate-screenshots.sh) | Bash | Atomique | ExĂ©cute les tests d'UI Robolectric/Roborazzi pour gĂ©nĂ©rer ou mettre Ă  jour les captures d'Ă©cran en local. | `sync-stitch`, GĂ©nĂ©ration des captures Roborazzi | -| [`scripts/upload-screenshots.py`](../scripts/upload-screenshots.py) | Python 3 | Atomique | Valide et mappe les 10 captures Roborazzi sur les `screen_id` Stitch existants pour mise Ă  jour in-place (zĂ©ro hallucination). | `sync-stitch`, `upload-screenshots.py` | -| [`scripts/cleanup-e2e-firestore.mjs`](../scripts/cleanup-e2e-firestore.mjs) | Node.js (ESM) | Atomique | Purge les documents de sondes de test crĂ©Ă©s dans la collection Firestore `/users`. | Maintenance et tests de sonde | -| [`scripts/inspect-ide.sh`](../scripts/inspect-ide.sh) | Bash | Atomique | ExĂ©cute le moteur d'inspection complet d'Android Studio / IntelliJ en mode headless avec profil par dĂ©faut. | Audit qualitĂ© avancĂ© IDE | +| [`scripts/validate-docs.sh`](../scripts/validate-docs.sh) | Bash | Atomic | Validates structural integrity and byte budget compliance across all architecture contracts (`DESIGN.md`, `design-system.md`, `AGENTS.md`, playbooks, skills, rules). | `quality-airbag`, `sync-stitch`, `delivery-pipeline.yml` | +| [`scripts/quality-check.sh`](../scripts/quality-check.sh) | Bash | Atomic | Executes the full Gradle suite: Kotlin/Java compilation, Android Lint Debug/Release, unit tests, and Robolectric/Roborazzi UI tests. | `quality-airbag`, `open-pr`, `delivery-pipeline.yml` | +| [`scripts/test-runtime-guardrails.mjs`](../scripts/test-runtime-guardrails.mjs) | Node.js (ESM) | Atomic | Runs 18 security assertions verifying PoLP tool revocation, `plan-guard.mjs`, and `branch-guard.mjs` path hardening. | `quality-airbag`, CI | +| [`scripts/install-hooks.sh`](../scripts/install-hooks.sh) | Bash | Atomic | Binds local Git hooks to `.agent/hooks/` and guarantees executable permissions on all hook scripts. | Developer onboarding, setup | +| [`scripts/deploy-app-distribution.sh`](../scripts/deploy-app-distribution.sh) | Bash | Atomic | Builds the APK and deploys to Firebase App Distribution with monotonic version multiplier (x100) and formatted release notes. | `distribute-local`, Ad-hoc tester release | +| [`scripts/generate-screenshots.sh`](../scripts/generate-screenshots.sh) | Bash | Atomic | Executes Robolectric/Roborazzi UI tests to record and generate local screenshots in `build/outputs/roborazzi`. | `sync-stitch`, Design System capture update | +| [`scripts/upload-screenshots.py`](../scripts/upload-screenshots.py) | Python 3 | Atomic | Validates and maps Roborazzi screenshot baselines to Google Stitch `screen_id`s for in-place synchronization. | `sync-stitch`, `upload-screenshots.py` | +| [`scripts/inspect-ide.sh`](../scripts/inspect-ide.sh) | Bash | Atomic | Executes Android Studio / IntelliJ IDEA code inspection engine in headless mode with default project profiles. | Advanced IDE quality audit | --- -## 3. Fiches DĂ©taillĂ©es par Script +## 3. Detailed Script Reference Sheets ### 3.1 `scripts/validate-docs.sh` -* **RĂŽle** : Gardien de l'intĂ©gritĂ© documentaire et de la conformitĂ© des contrats d'architecture. -* **VĂ©rifications effectuĂ©es** : - - PrĂ©sence de `DESIGN.md`, `design-system.md`, `agent.md`, `README.md`, `README.fr.md`. - - PrĂ©sence des rĂšgles maĂźtresses : `agent-lifecycle.md`, `backlog-planner.md`, `git-workflow.md`. - - PrĂ©sence des playbooks : `room-migrations.md`, `firestore-security.md`, `roborazzi-export.md`, `compose-theming.md`. - - PrĂ©sence des compĂ©tences sĂ©mantiques : `plan-issue.md`, `open-pr.md`, `quality-airbag.md`, `distribute-local.md`, `triage-feedback.md`, `sync-stitch.md`. - - ValiditĂ© du frontmatter YAML dans `DESIGN.md` (`Serene Intellectual`). -* **Utilisation** : +* **Role**: Quality gatekeeper for documentation integrity and multi-agent architectural contract compliance. +* **Checks performed**: + - Presence of core contracts: `DESIGN.md`, `design-system.md`, `AGENTS.md`, `agent.md`, `README.md`, `ARCHITECTURE.md`. + - Presence and size budgets of master rules: `agent-lifecycle.md`, `backlog-planner.md`, `git-workflow.md`, `firebase-standards.md`. + - Presence and size budgets of playbooks: `room-migrations.md`, `roborazzi-export.md`, `compose-theming.md`, `android-standards.md`. + - Presence of semantic skills: `plan-issue`, `open-pr`, `quality-airbag`, `sync-stitch`. + - Presence and executable flags on hooks: `pre-commit-airbag.sh`, `post-merge-dual-sync.sh`, `branch-guard.mjs`, `plan-guard.mjs`, `pre-invocation-anchor.sh`. + - YAML frontmatter validity in `DESIGN.md` (`Serene Intellectual`). +* **Usage**: ```bash ./scripts/validate-docs.sh ``` -* **Codes de sortie** : `0` (SuccĂšs, 100% validĂ©), `1` (Échec, au moins un fichier ou contrat manquant). +* **Exit Codes**: `0` (Success, 100% validated), `1` (Failure, at least one contract or file missing/over-budget). --- ### 3.2 `scripts/quality-check.sh` -* **RĂŽle** : Airbag qualitĂ© de compilation et d'analyse statique Android. -* **Actions exĂ©cutĂ©es** : - - DĂ©tection et initialisation automatique de `JAVA_HOME` (Android Studio JBR / JDK 21). - - ExĂ©cution de `./gradlew codeSanityCheck --stacktrace` : - 1. Compilateur Kotlin (checks progressifs & annotations opt-in). - 2. Compilateur Java (`-Xlint:all`). - 3. Android Lint Debug & Release (Compose, sĂ©curitĂ©, i18n, performance). - 4. Tests unitaires et tests UI Robolectric (135+ tests). - 5. CompatibilitĂ© Jetifier & AndroidX. -* **Utilisation** : +* **Role**: Primary compilation and static analysis airbag for Android. +* **Actions executed**: + - Automatic detection and portable configuration of `JAVA_HOME` (Android Studio JBR / JDK 21). + - Execution of `./gradlew codeSanityCheck --stacktrace`: + 1. Kotlin compiler checks (progressive mode & opt-in annotations). + 2. Java compiler warnings (`-Xlint:all`). + 3. Android Lint Debug & Release (Compose, security, i18n, performance). + 4. Unit tests and Robolectric/Roborazzi UI tests. +* **Usage**: ```bash ./scripts/quality-check.sh ``` -* **Rapports gĂ©nĂ©rĂ©s** : +* **Generated Reports**: - `app/build/reports/lint-results-debug.html` - `app/build/reports/lint-results-release.html` - `app/build/reports/tests/testDebugUnitTest/index.html` --- -### 3.3 `scripts/test-firestore-rules.mjs` -* **RĂŽle** : Suite de tests de sĂ©curitĂ© et de non-rĂ©gression hors-ligne pour `firestore.rules`. -* **VĂ©rifications assurĂ©es (16 assertions)** : - - **Suite 1 (Structure)** : `rules_version = '2'`, helpers `isAuthenticated()`, `isCoupleMember()`, `isMemberOfCouple()`. - - **Suite 2 (AccĂšs Moindre PrivilĂšge)** : Cloisonnement `/users/{userId}`, `/invites/`, `/pairings/`, `/couples/{coupleId}`, `/loads/{loadId}`, rejet par dĂ©faut `allow read, write: if false;`. - - **Suite 3 (Anti-RĂ©gression)** : 0 rĂšgle ouverte `if true`, 0 Ă©criture non vĂ©rifiĂ©e `if request.auth != null`, isolation stricte des sanctuaires de test `SANCTUARY-TEST*`. -* **Utilisation** : +### 3.3 `scripts/test-runtime-guardrails.mjs` +* **Role**: Offline security test suite for runtime guardrails and PoLP persona configurations. +* **Verifications (18 assertions)**: + - **PoLP Tool Access**: Verifies `run_command` is denied/revoked for P1, P2, P3, and P4 personas. + - **Plan Guard (`plan-guard.mjs`)**: Rejection of `--no-verify`, `-c core.hooksPath` bypasses, commits on `main`, and pushes to `main`. + - **Branch Guard (`branch-guard.mjs`)**: Canonical path hardening preventing write operations to repository files while on `main`. +* **Usage**: ```bash - node scripts/test-firestore-rules.mjs + node scripts/test-runtime-guardrails.mjs ``` --- -### 3.4 `scripts/deploy-firestore-rules.mjs` -* **RĂŽle** : DĂ©ploiement programmatique sĂ©curisĂ© des rĂšgles Firestore sans dĂ©pendre de la CLI Firebase. -* **Fonctionnement** : - 1. Lit `service-account.json` et gĂ©nĂšre un JWT signĂ© RSA-SHA256 (scope `cloud-platform datastore`). - 2. CrĂ©e un nouveau ruleset via l'API REST `firebaserules.googleapis.com/v1/projects/{projectId}/rulesets`. - 3. Met Ă  jour la release `projects/{projectId}/releases/cloud.firestore`. -* **PrĂ©requis** : `service-account.json` valide avec rĂŽle Firebase Rules Admin. -* **Utilisation** : +### 3.4 `scripts/install-hooks.sh` +* **Role**: Binds local Git hooks to `.agent/hooks/` and guarantees executable permissions. +* **Actions executed**: + - Sets executable permissions on `.agent/hooks/*.sh` and `*.mjs`. + - Symlinks standard Git `pre-commit` to `pre-commit-airbag.sh`. + - Configures Git `core.hooksPath` to `.agent/hooks`. +* **Usage**: ```bash - node scripts/deploy-firestore-rules.mjs + ./scripts/install-hooks.sh ``` --- ### 3.5 `scripts/deploy-app-distribution.sh` -* **RĂŽle** : Construction et distribution directe sur Firebase App Distribution depuis le terminal local. -* **Fonctionnement** : - 1. DĂ©tecte `service-account.json`. - 2. Calcule la version Git (`versionCode` = nombre total de commits, `versionName` = tag SemVer + commits ahead). - 3. Formate les notes de version : `v (build ) : `. - 4. Compile (`assembleDebug` ou `assembleRelease`) et tĂ©lĂ©verse (`appDistributionUploadDebug` ou `appDistributionUploadRelease`). - 5. Nettoie les fichiers temporaires `release-notes.txt`. -* **Arguments & Options** : - - `[notes]` : Message explicatif pour les testeurs (dĂ©faut : message du dernier commit Git). - - `[variant]` : `release` (dĂ©faut) ou `debug`. - - `--groups, -g` : Groupes de testeurs Firebase ciblĂ©s (dĂ©faut : `admin, testers`). -* **Exemples** : +* **Role**: Direct build and distribution to Firebase App Distribution from the local developer terminal. +* **Workflow**: + 1. Detects `service-account.json`. + 2. Calculates Git version metadata (`versionCode` using monotonic multiplier x100, `versionName` with SemVer tag and commits ahead). + 3. Formats release notes: `v (build ) : `. + 4. Compiles (`assembleDebug` or `assembleRelease`) and uploads (`appDistributionUploadDebug` or `appDistributionUploadRelease`). + 5. Cleans up temporary `release-notes.txt` artifacts. +* **Arguments & Options**: + - `[notes]`: User-facing message for testers (default: latest Git commit message). + - `[variant]`: `release` (default) or `debug`. + - `--groups, -g`: Targeted Firebase tester groups (default: `admin, testers`). +* **Examples**: ```bash - # 1. Distribution standard + # 1. Standard release distribution ./scripts/deploy-app-distribution.sh - # 2. Avec notes personnalisĂ©es - ./scripts/deploy-app-distribution.sh "Correction synchronisation duo" + # 2. With custom release notes + ./scripts/deploy-app-distribution.sh "Fix duo sync state" - # 3. Release APK pour testeurs internes + # 3. Release APK for internal admins ./scripts/deploy-app-distribution.sh "RC v0.2.0" release --groups "admin" ``` --- ### 3.6 `scripts/upload-screenshots.py` -* **RĂŽle** : Mappage et tĂ©lĂ©versement dĂ©terministe des captures Roborazzi sur les Ă©crans Stitch. -* **Garanties** : - - Mappage 1:1 strict entre 10 captures locales (`screenshots/stitch_export/*.png`) et 10 `screen_id` Google Stitch. - - Mise Ă  jour strictly in-place (interdiction formelle de crĂ©er des Ă©crans orphelins). - - Validation prĂ©alable de l'existence et du poids de chaque fichier PNG. -* **Options CLI** : - - `--project-id` : ID du projet Stitch (dĂ©faut : ``). - - `--check-only` : VĂ©rifie la prĂ©sence et le mappage des 10 PNGs sans tĂ©lĂ©versement. - - `--dry-run` : Simule l'exĂ©cution et affiche les payloads JSON/Base64. -* **Exemples** : +* **Role**: Deterministic mapping and upload of Roborazzi UI screenshots to Google Stitch screens. +* **Guarantees**: + - Strict 1:1 mapping between local snapshots (`screenshots/stitch_export/*.png`) and Google Stitch `screen_id`s. + - In-place screen updates preventing duplicate or orphaned screens in Stitch. + - Pre-validation of PNG file existence and non-zero byte size. +* **CLI Options**: + - `--project-id`: Google Stitch Project ID. + - `--check-only`: Verifies presence and mapping of PNG files without uploading. + - `--dry-run`: Simulates execution and outputs JSON/Base64 payloads. +* **Examples**: ```bash python3 scripts/upload-screenshots.py --check-only python3 scripts/upload-screenshots.py --dry-run @@ -183,46 +180,34 @@ graph TD --- ### 3.7 `scripts/generate-screenshots.sh` -* **RĂŽle** : ExĂ©cute les tests d'UI Robolectric et Roborazzi pour enregistrer et gĂ©nĂ©rer localement les captures d'Ă©cran de l'application dans `build/outputs/roborazzi`. -* **Fonctionnement** : - - Lance `./gradlew recordRoborazziDebug --stacktrace`. - - Produit les captures d'Ă©cran requises pour la validation et la synchronisation du Design System. -* **Utilisation** : +* **Role**: Executes Robolectric and Roborazzi UI tests to record and update application screenshots locally in `build/outputs/roborazzi`. +* **Workflow**: + - Executes `./gradlew recordRoborazziDebug --stacktrace`. + - Produces verified screenshot assets required for Design System synchronization. +* **Usage**: ```bash ./scripts/generate-screenshots.sh ``` --- -### 3.8 `scripts/cleanup-e2e-firestore.mjs` -* **RĂŽle** : Nettoyage et purge des documents Firestore de sonde crĂ©Ă©s lors des tests d'authentification ou d'intĂ©gritĂ©. -* **Fonctionnement** : - - S'authentifie via `service-account.json`. - - Liste les documents sous `/users` crĂ©Ă©s par les sondes de test. - - Supprime chaque document unitairement via l'API REST Firestore. -* **Utilisation** : - ```bash - node scripts/cleanup-e2e-firestore.mjs - ``` - ---- - -### 3.9 `scripts/inspect-ide.sh` -* **RĂŽle** : Inspection headless IntelliJ / Android Studio. -* **Utilisation** : +### 3.8 `scripts/inspect-ide.sh` +* **Role**: Headless IntelliJ IDEA / Android Studio static inspection runner. +* **Usage**: ```bash ./scripts/inspect-ide.sh ``` --- -## 4. Matrice de Composition (Skills & Pipelines ➔ Scripts & MCP) +## 4. Composition Matrix (Skills & Pipelines ➔ Scripts & MCP) -| Skill / Pipeline | Outils InvoquĂ©s (dans l'ordre d'exĂ©cution) | +| Skill / Pipeline | Invoked Tools (in execution order) | |---|---| -| **`quality-airbag`** (`/quality-check`) | 1. `scripts/validate-docs.sh`
2. `scripts/quality-check.sh`
3. `scripts/test-firestore-rules.mjs` | -| **`open-pr`** (`/open-pr`) | 1. `scripts/quality-check.sh` (Airbag qualité complet) | -| **`distribute-local`** (`/distribute-local`) | 1. `scripts/quality-check.sh` (Recommandé)
2. `scripts/deploy-app-distribution.sh` | +| **`quality-airbag`** (`/quality-check`) | 1. `scripts/validate-docs.sh`
2. `scripts/quality-check.sh`
3. `scripts/test-runtime-guardrails.mjs` | +| **`open-pr`** (`/open-pr`) | 1. `scripts/quality-check.sh` (Full quality airbag)
2. Walkthrough generation & PR creation | +| **`distribute-local`** (`/distribute-local`) | 1. `scripts/quality-check.sh` (Recommended)
2. `scripts/deploy-app-distribution.sh` | | **`sync-stitch`** (`/sync-stitch`) | 1. `scripts/validate-docs.sh`
2. `scripts/generate-screenshots.sh`
3. `scripts/upload-screenshots.py` | -| **`triage-feedback`** (`/triage-feedback`) | 100% MCP natif (`GitHubMCP` : `search_issues`, `add_issue_comment`, `create_issue`) | -| **Delivery Pipeline & Quality Gate (`delivery-pipeline.yml`)** | 1. `scripts/validate-docs.sh`
2. `scripts/quality-check.sh` (`./gradlew codeSanityCheck`)
3. Compilation & Firebase App Distribution via Gradle | +| **`triage-feedback`** (`/triage-feedback`) | 100% native MCP (`GitHubMCP`: `search_issues`, `add_issue_comment`, `create_issue`) | +| **Delivery Pipeline & Quality Gate (`delivery-pipeline.yml`)** | 1. `scripts/validate-docs.sh`
2. `scripts/quality-check.sh` (`./gradlew codeSanityCheck`)
3. APK build & Firebase App Distribution deployment via Gradle | + From 561a77475e52ec8e3cb69750637ef38a04da157c Mon Sep 17 00:00:00 2001 From: NicolasVD Date: Fri, 25 Sep 2026 12:36:00 +0200 Subject: [PATCH 2/2] docs(i18n): generalize analytics taxonomy and QA test guide for kernel reuse - Generalize docs/analytics-taxonomy.md into canonical Zero-PII kernel contract - Generalize docs/qa-classification-test-guide.md to Two-Tier AI and 3-State QA reference - Remove project-specific Second Brain entity and test strings Ref #10 --- docs/analytics-taxonomy.md | 135 +++++++++++---------- docs/qa-classification-test-guide.md | 168 ++++++++++++++------------- 2 files changed, 164 insertions(+), 139 deletions(-) diff --git a/docs/analytics-taxonomy.md b/docs/analytics-taxonomy.md index 24990aa..38618b4 100644 --- a/docs/analytics-taxonomy.md +++ b/docs/analytics-taxonomy.md @@ -1,117 +1,130 @@ -# 📊 Analytics Taxonomy & Events (Zero-PII & Privacy-First) +# 📊 Zero-PII Analytics & Telemetry Taxonomy Contract -This document formalizes the telemetry structure, event catalog, and parameters for the **Agentic Android Kernel**. +This document formalizes the telemetry structure, event taxonomy, and privacy invariants for applications built on the **Agentic Android Delivery Kernel**. --- ## đŸ›Ąïž 1. Privacy Principles & Ethics (Zero-PII) -The telemetry architecture of Agentic Android Kernel is designed under the strict principle of **Privacy by Design**: +The telemetry architecture of the Agentic Android Delivery Kernel enforces a strict **Privacy by Design** foundation: -1. **Zero Personally Identifiable Information (Zero-PII)**: Task titles, descriptions, personal names, email addresses, and user-generated text are **never** transmitted in analytics events. -2. **Bucketing / Value Ranges**: All text lengths and item counts are grouped into discrete intervals (e.g., `1-20`, `21-50`, `51-100`, `100+`) to prevent indirect fingerprinting through textual cardinality. -3. **Robust & Offline Behavior**: If Firebase Analytics is uninitialized or in airplane mode, the tracker safely encapsulates calls without causing crashes or blocking the UI (`FirebaseAnalyticsTracker`). +1. **Zero Personally Identifiable Information (Zero-PII)**: User-generated content, free-form text, titles, notes, personal names, email addresses, and phone numbers are **strictly prohibited** in analytics event parameters. +2. **Cardinality Control & Bucketing**: All textual lengths, item quantities, and durations must be grouped into discrete intervals (e.g., `1-10`, `11-20`, `21-50`, `50+` or `0`, `1-5`, `6-15`, `16-30`, `30+`) to eliminate indirect user fingerprinting. +3. **Graceful Degradation & Offline Safety**: If the analytics provider is uninitialized, blocked by network configuration, or in airplane mode, the tracking layer safely encapsulates calls without causing runtime exceptions or blocking the main thread. --- -## 📈 2. User Properties +## 📈 2. Canonical User Properties -| Key | Type | Example Values | Description | +User properties capture macro-level application state without storing individual behavioral profiles: + +| Property Key | Type | Example Values | Description | |---|---|---|---| -| `access_state` | String | `guest`, `solo`, `duo` | Current access state (Guest, Authenticated Solo, Paired Duo). | -| `theme_preference` | String | `light`, `dark`, `system` | Display theme preference. | -| `is_partner_linked` | Boolean | `true`, `false` | Indicates whether the account is paired with a partner. | -| `active_loads_bucket` | String | `0`, `1-5`, `6-15`, `16-30`, `30+` | Bucket of active mental load items. | -| `focus_streak_bucket` | String | `0`, `1-3`, `4-7`, `8-14`, `15-30`, `30+` | Daily active prioritization streak bucket. | +| `access_state` | String | `guest`, `solo`, `duo` | Current access level within the 3-State Access Matrix. | +| `theme_preference` | String | `light`, `dark`, `system` | Active UI theme preference. | +| `account_link_state` | String | `anonymous`, `authenticated_solo`, `paired_shared` | Identity and authentication topology. | +| `active_entities_bucket` | String | `0`, `1-5`, `6-15`, `16-30`, `30+` | Total volume of active domain entities managed by the user. | +| `engagement_streak_bucket` | String | `0`, `1-3`, `4-7`, `8-14`, `15-30`, `30+` | Daily usage and prioritization streak interval. | --- -## đŸ·ïž 3. Event Catalog by Functional Domain +## đŸ·ïž 3. Event Taxonomy by Functional Domain + +### 🧠 A. AI Assistance & Two-Tier Classification -### 🧠 A. Artificial Intelligence & Two-Tier Classification (Issue #2) +Telemetry events measuring the accuracy, latency, and user adoption of AI suggestions: | Event Name | Parameters | Description | |---|---|---| -| `ai_classification_triggered` | `input_length_bucket` (String: `1-10`, `11-20`, `21-50`, `50+`)
`has_partner_context` (Boolean) | Triggered when evaluating cognitive workload for a task. | -| `ai_quadrant_suggested` | `source` (String: `heuristic`, `gemini_flash`)
`suggested_quadrant` (String: `do_today`, `schedule`, `delegate`, `park`)
`suggested_area` (String: `self`, `home`, `work`)
`confidence_bucket` (String: `high`, `medium`, `low`) | Emitted when a quadrant and life area suggestion is presented to the user. | -| `ai_quadrant_applied` | `quadrant` (String)
`area` (String)
`source` (String)
`time_to_apply_ms` (Long) | Recorded when the user taps the suggestion chip to apply it in 1-tap. | -| `ai_quadrant_dismissed` | `suggested_quadrant` (String)
`manual_selected_quadrant` (String)
`suggested_area` (String, opt)
`manual_selected_area` (String, opt) | Recorded when the user dismisses or overrides the AI suggestion with a manual selection. | +| `ai_classification_triggered` | `input_length_bucket` (String: `1-10`, `11-20`, `21-50`, `50+`)
`has_context` (Boolean) | Triggered when cognitive evaluation of an input starts. | +| `ai_suggestion_presented` | `source` (String: `heuristic`, `cloud_llm`)
`suggested_category` (String)
`suggested_priority` (String)
`confidence_bucket` (String: `high`, `medium`, `low`) | Emitted when an AI recommendation is displayed in the UI. | +| `ai_suggestion_applied` | `category` (String)
`priority` (String)
`source` (String)
`time_to_apply_ms` (Long) | Recorded when the user applies an AI suggestion with a 1-tap interaction. | +| `ai_suggestion_dismissed` | `suggested_category` (String)
`manual_override_selected` (String)
`source` (String) | Recorded when the user dismisses or manually overrides the AI recommendation. | --- -### 📝 B. Quick Capture & Mental Load Management +### 📝 B. Entity Lifecycle & Data Operations + +Lifecycle events tracking the creation, mutation, and completion of domain entities: | Event Name | Parameters | Description | |---|---|---| -| `quick_capture_submitted` | `char_count_bucket` (String: `1-20`, `21-50`, `51-100`, `100+`)
`has_details` (Boolean) | Submitting a thought from the home capture bar. | -| `mental_load_created` | `area` (String: `self`, `home`, `work`)
`quadrant` (String)
`is_shared` (Boolean)
`is_ai_assisted` (Boolean) | Creating and saving a new mental load item. | -| `mental_load_updated` | `area` (String)
`quadrant` (String)
`is_shared` (Boolean)
`changed_quadrant` (Boolean)
`changed_area` (Boolean) | Updating properties of an existing task. | -| `mental_load_deleted` | `area` (String)
`quadrant` (String)
`was_completed` (Boolean)
`was_shared` (Boolean) | Deleting a mental load item. | -| `task_completed` | `area` (String)
`quadrant` (String)
`is_shared` (Boolean)
`is_voted_today` (Boolean) | Checking / completing a task. | -| `task_reopened` | `area` (String)
`quadrant` (String)
`is_shared` (Boolean) | Reopening a completed task. | -| `task_filter_applied` | `filter_mode` (String: `all`, `shared`, `personal`, `top3`)
`results_count` (Int) | Applying a filter on the task list. | +| `quick_capture_submitted` | `char_count_bucket` (String: `1-20`, `21-50`, `51-100`, `100+`)
`has_details` (Boolean) | Rapid thought or item capture from entry surfaces. | +| `entity_created` | `category` (String)
`priority_tier` (String)
`is_shared` (Boolean)
`is_ai_assisted` (Boolean) | Creation and persistence of a new domain entity. | +| `entity_updated` | `category` (String)
`changed_category` (Boolean)
`changed_priority` (Boolean)
`is_shared` (Boolean) | Mutation of existing entity attributes. | +| `entity_deleted` | `category` (String)
`was_completed` (Boolean)
`was_shared` (Boolean) | Entity deletion from local or remote stores. | +| `entity_completed` | `category` (String)
`priority_tier` (String)
`is_shared` (Boolean) | Marking an entity as resolved or completed. | +| `entity_reopened` | `category` (String)
`is_shared` (Boolean) | Reopening a previously completed entity. | +| `entity_filter_applied` | `filter_mode` (String: `all`, `shared`, `personal`, `priority`)
`results_count_bucket` (String) | Filtering entity lists or collection views. | --- -### 🧭 C. Eisenhower Matrix & Daily Prioritization +### 🧭 C. Priority Matrix & Workflow State + +Events monitoring workflow state transitions and daily prioritization: | Event Name | Parameters | Description | |---|---|---| -| `daily_vote_toggled` | `action` (String: `added`, `removed`)
`current_voted_count` (Int: `1` to `3`)
`area` (String)
`quadrant` (String) | Adding or removing a task from the daily Top 3. | -| `daily_vote_limit_reached` | `max_votes` (Int: `3`)
`active_loads_count` (Int) | Attempting to exceed the 3-vote daily limit. | -| `daily_votes_reset` | `previous_voted_count` (Int) | Daily reset of Top 3 votes. | -| `quadrant_reassigned` | `previous_quadrant` (String, opt)
`target_quadrant` (String)
`area` (String) | Direct reassignment of a task to another quadrant. | +| `priority_item_toggled` | `action` (String: `added`, `removed`)
`current_priority_count` (Int)
`category` (String) | Adding or removing an item from primary focus. | +| `priority_limit_reached` | `max_limit` (Int)
`active_items_count` (Int) | User notification when attempting to exceed daily focus caps. | +| `priority_batch_reset` | `previous_count` (Int) | Scheduled or manual reset of high-priority focus items. | +| `workflow_state_reassigned` | `previous_state` (String, opt)
`target_state` (String)
`category` (String) | Moving an entity across workflow states or quadrants. | --- -### đŸ‘« D. Duo Space & Partner Pairing +### đŸ‘« D. Duo Collaboration & Real-Time Sync + +Telemetry covering shared state, pairing rituals, and collaborative interactions: | Event Name | Parameters | Description | |---|---|---| -| `partner_invite_generated` | `is_regenerated` (Boolean) | Generating a sanctuary code `SANCTUARY-XXXXXX`. | -| `partner_join_attempted` | `code_format_valid` (Boolean) | Submitting a partner invitation code. | -| `partner_paired_success` | `method` (String: `sanctuary_code`) | Successful pairing of both profiles. | -| `partner_paired_failed` | `error_reason` (String) | Pairing failure (invalid code, already linked). | -| `partner_unpaired` | `active_tasks_count` (Int) | Unpairing from partner. | -| `partner_upvote_toggled` | `action` (String)
`area` (String)
`is_completed` (Boolean) | Support/priority vote on a shared task. | -| `partner_ledger_viewed` | `active_dimension` (String)
`total_shared_tasks` (Int) | Viewing the Synergy Ledger. | -| `partner_ledger_dim_changed`| `selected_dimension` (String: `active`, `initiated`, `resolved`)
`user_percentage` (Int)
`partner_percentage` (Int) | Switching between the 3 couple workload dimensions. | -| `couple_synergy_viewed` | `focus_streak_days` (Int)
`total_completed_shared` (Int) | Opening the couple synergy celebration modal. | -| `shared_privacy_updated` | `privacy_mode` (String) | Updating shared tasks visibility mode. | +| `pairing_invite_generated` | `is_regenerated` (Boolean) | Generating a secure pairing or invitation code. | +| `pairing_join_attempted` | `code_format_valid` (Boolean) | Submitting an invitation code to join a shared workspace. | +| `pairing_success` | `method` (String: `invite_code`, `qr`, `link`) | Successful establishment of a shared session. | +| `pairing_failed` | `error_reason` (String) | Pairing error (expired token, mismatched version, already linked). | +| `pairing_disconnected` | `active_shared_count` (Int) | Unlinking from a shared workspace. | +| `collaborator_interaction` | `action` (String)
`category` (String)
`is_completed` (Boolean) | Collaborative action or support vote on a shared item. | +| `shared_ledger_viewed` | `active_dimension` (String)
`total_shared_items` (Int) | Inspecting shared collaboration metrics or ledgers. | +| `shared_privacy_updated` | `privacy_mode` (String) | Updating visibility or permission rules for shared data. | --- -### 🔐 E. Authentication, Soft-Gating & Settings +### 🔐 E. Authentication, Soft-Gating & System Settings + +Core system lifecycle, authentication flows, and accessibility preferences: | Event Name | Parameters | Description | |---|---|---| -| `screen_view` | `screen_name` (String)
`screen_class` (String)
`access_state` (String)
`active_loads_count` (Int)
`voted_loads_count` (Int) | Navigating to a screen. | -| `sign_in_started` | `source` (String) | Initiating Google Sign-In. | -| `sign_in_success` | *(none)* | Successful sign-in. | -| `sign_in_failed` | `error_type` (String)
`error_message` (String) | Google Sign-In failure. | -| `sign_out` | `previous_access_state` (String) | Voluntary user sign-out. | -| `soft_gate_shown` | `trigger_feature` (String) | Displaying sign-in/pairing soft-gate modal. | -| `theme_changed` | `new_theme` (String)
`previous_theme` (String, opt) | Changing theme mode (Light / Dark / System). | -| `gentle_reset_started` | `source` (String) | Launching 4-4-4 guided breathing session. | -| `gentle_reset_completed` | `duration_seconds` (Int: `30`)
`current_streak` (Int) | Completing a zen centering session. | +| `screen_view` | `screen_name` (String)
`screen_class` (String)
`access_state` (String)
`active_items_bucket` (String) | Screen navigation tracking. | +| `sign_in_started` | `source` (String) | Initiating an authentication provider flow. | +| `sign_in_success` | `provider` (String: `google`, `credential`) | Successful identity authentication. | +| `sign_in_failed` | `error_type` (String)
`error_message` (String) | Authentication failure or cancellation. | +| `sign_out` | `previous_access_state` (String) | User-initiated sign-out. | +| `soft_gate_prompt_shown` | `trigger_feature` (String)
`target_state` (String) | Prompting an unauthenticated user to sign in or pair. | +| `theme_changed` | `new_theme` (String)
`previous_theme` (String, opt) | Theme mode change (Light, Dark, System). | --- -### 🔁 F. Recurrence, Due Dates & Alternating Duo Rotation (Issue #1) +### 🔁 F. Recurrence, Scheduling & Workload Rotation + +Events governing temporal rules, recurring schedules, and collaborative rotation: | Event Name | Parameters | Description | |---|---|---| -| `task_due_date_set` | `is_preset` (Boolean)
`preset_type` (String, opt: `today`, `tomorrow`, `weekend`, `next_week`)
`is_recurring` (Boolean)
`days_until_due` (Int, opt) | Setting or quick-selecting a due date on a mental load item. | -| `recurring_task_created` | `frequency` (String: `daily`, `weekdays_only`, `weekends_only`, `weekly`, `biweekly`, `monthly`, `yearly`)
`is_duo_rotating` (Boolean)
`has_due_date` (Boolean)
`area` (String) | Creating a recurring or periodic task. | -| `recurring_task_completed` | `frequency` (String)
`cycle_count` (Int)
`is_duo_rotating` (Boolean)
`has_due_date` (Boolean) | Completing a recurring task cycle and triggering the next cycle. | -| `duo_rotation_assigned` | `frequency` (String)
`cycle_count` (Int)
`next_assignee_role` (String: `partner`, `self`)
`days_to_next_due` (Int, opt) | Automatic alternation of task assignee for the next cycle. | +| `entity_due_date_set` | `is_preset` (Boolean)
`preset_type` (String, opt)
`is_recurring` (Boolean)
`days_until_due_bucket` (String, opt) | Setting a deadline or due date on an entity. | +| `recurring_rule_created` | `frequency` (String: `daily`, `weekly`, `monthly`, `custom`)
`is_shared_rotating` (Boolean)
`category` (String) | Creating an automated recurrence schedule. | +| `recurring_cycle_completed` | `frequency` (String)
`cycle_count` (Int)
`is_shared_rotating` (Boolean) | Completing a cycle and generating the next scheduled instance. | +| `rotation_assigned` | `frequency` (String)
`cycle_count` (Int)
`next_assignee_role` (String: `partner`, `self`, `team`) | Automatic rotation of responsibility across collaborators. | --- -## đŸ§Ș 4. Validation & Automated Tests +## đŸ§Ș 4. Automated Verification -All events and parameter serializations are validated in unit tests: +All analytics events and parameter bundle builders must be validated with unit tests verifying: +1. Zero PII parameter keys and value formats. +2. Proper bucketing of numeric and length inputs. +3. Safe execution when analytics dependencies are mocked or disabled. ```bash -./gradlew testDebugUnitTest --tests com.secondbrain.app.data.analytics.AnalyticsTrackerTest +./gradlew testDebugUnitTest --tests "*AnalyticsTrackerTest*" ``` diff --git a/docs/qa-classification-test-guide.md b/docs/qa-classification-test-guide.md index 62c8828..cd76719 100644 --- a/docs/qa-classification-test-guide.md +++ b/docs/qa-classification-test-guide.md @@ -1,116 +1,128 @@ -# 🧠 QA Test Guide & AI Classification Reference (Clarity Matrix & Areas of Life) +# 🧠 QA Test Guide & Two-Tier AI Verification Reference -This document details the cognitive management philosophy of **Agentic Android Kernel**, the behavior of the **Two-Tier hybrid classification engine (Local Heuristic + Gemini Flash-Lite)**, and the **exhaustive test matrix (all 12 combinations)** used to validate quadrant and life area suggestions. +This document establishes the quality assurance standards, defect classification matrix, and verification protocols for applications powered by the **Agentic Android Delivery Kernel**, with emphasis on the **Two-Tier Hybrid AI Architecture (Local Heuristics + Cloud LLM)** and the **3-State Access Matrix**. --- -## 🌿 1. Philosophy & Positive Emotional Vocabulary +## 🚩 1. Defect Severity & Classification Matrix -Agentic Android Kernel applies principles from the **Eisenhower Matrix** and the **GTD (Getting Things Done)** methodology, reinterpreted through a calming approach (*Serene UX*): +Persona 6 (Release Manager) and QA engineers qualify all anomalies and regressions using three standard severity tiers: -* **Zero Stress / Non-prescriptive**: The interface avoids anxiety-inducing terminology. -* **Duo Teamwork**: The traditional *"Delegate"* label is replaced by **"Duo Teamwork"** and **"Propose to partner"**, emphasizing positive interdependence and shared mental load reduction. -* **Mental Sanctuary**: The *"Eliminate / Won't do"* quadrant is replaced by **"Park in Sanctuary"**, providing a space to capture valuable thoughts without deadlines or guilt. +| Severity | Criteria | Impact | SLA / Resolution Path | +|---|---|---|---| +| **P0 · Blocker** | Application crash on launch, fatal exception, database migration corruption, security bypass, or broken primary user flow. | Total blockage or data loss. | Immediate triage, circuit breaker halted, hotfix release. | +| **P1 · Major** | Functional flow regression without viable workaround, sync failure in Duo state, authentication loop, or AI suggestion failure with no local fallback. | Degraded core functionality. | Blocking for milestone release train; fixed in active sprint. | +| **P2 · Minor** | Visual glitch, theme token misalignment, animation stutter, minor localization typo, or non-blocking edge-case delay. | Cosmetic or low friction. | Scheduled in standard backlog sprint. | + +### 🔍 Bug Report Qualification Checklist +Before submitting a defect, verify: +1. **Deterministic Steps to Reproduce**: Minimal step-by-step sequence from a clean application state. +2. **Environment Specification**: Device model, Android OS version / API level, and build variant (`debug` vs `release`). +3. **Behavioral Contrast**: Clear statement of Expected Behavior vs Actual Observed Behavior. +4. **Logcat / Stacktrace**: Clean log snippet isolated to application process, sanitized of any PII. --- -## 🧭 2. The 4 Clarity Matrix Quadrants +## 🧭 2. 3-State Access Matrix QA Protocols + +Every feature and data flow must be verified across the 3 fundamental access states: ``` - URGENT (Short Term) NON-URGENT (Long Term) - ┌───────────────────────────────────┬───────────────────────────────────┐ - │ ⚡ DO TODAY │ 🌿 SCHEDULE & ALIGN │ - IMPORTANT │ ‱ High urgency & high impact │ ‱ High impact, serene execution │ - (High Value) │ ‱ Imminent deadline (tonight) │ ‱ Structuring projects, Self-care│ - ├───────────────────────────────────┌──────────────────────────────────── - │ đŸ€ DUO TEAMWORK │ 🍃 PARK IN SANCTUARY │ - NON-IMPORTANT │ ‱ Urgent, low complexity │ ‱ Low urgency & low impact │ - (Low Load) │ ‱ Propose to partner │ ‱ Someday-maybe, Wishlist │ - └───────────────────────────────────┮───────────────────────────────────┘ + ┌────────────────────────────────────────────────────────┐ + │ 3-STATE ACCESS ARCHITECTURE │ + └────────────────────────────────────────────────────────┘ + │ │ │ + â–Œ â–Œ â–Œ + ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ + │ GUEST STATE │ │ SOLO STATE │ │ DUO STATE │ + │ 100% Local │ │ Personal Cloud│ │ Shared Sync │ + └───────────────┘ └───────────────┘ └───────────────┘ ``` -### 🔍 Focus: "Schedule & Align" vs. "Park in Sanctuary" +### A. Guest State (Unauthenticated / Offline) +* **Storage Invariant**: 100% local persistence via Room SQLite. +* **Network Invariant**: Zero unsolicited cloud database or storage network requests. +* **Soft-Gating**: Attempting to access cloud synchronization or partner pairing triggers a gentle non-blocking sign-in dialogue without crashing. -A fundamental distinction exists between these two categories: +### B. Solo State (Authenticated User) +* **Namespace Isolation**: Reads and writes are scoped strictly to the authenticated user's private cloud namespace (e.g., `/users/{userId}`). +* **Telemetry & Settings**: User preferences, theme modes, and Zero-PII analytics operate in personal mode. -1. **🌿 Schedule & Align (`SCHEDULE` - Quadrant II)**: - * This is the **"Golden Quadrant"** of calm efficiency. - * It gathers essential actions deserving deliberate attention without panic: medical checkups, life intentions, strategic roadmaps, and **active self-care**. - * 👉 *Example:* **"Take time for myself"** or **"Book doctor checkup"** are classified here because personal balance is an **important** intention that should be planned calmly. - -2. **🍃 Park in Sanctuary (`PARK` - Quadrant IV / Someday-Maybe)**: - * A dedicated space to **free the mind** from commitments with zero immediate urgency. - * It welcomes exploratory curiosities, wishlists, and distant ambitions stored safely without cluttering current attention. - * 👉 *Example:* **"Idea for later: try aerial yoga someday"** or **"Someday learn how to play piano"**. +### C. Duo State (Shared Collaboration) +* **Shared Workspace**: Real-time bidirectional synchronization scoped to the shared workspace namespace. +* **Concurrency & Conflicts**: Verified using 2 simultaneous test devices/emulators to validate conflict resolution. +* **Pairing Lifecycle**: Complete end-to-end verification of pairing generation, code submission, active sync, and clean disconnection. --- -## đŸ·ïž 3. The 3 Areas of Life +## ⚡ 3. Two-Tier Hybrid AI Engine Architecture -1. **🧘 For Self (`SELF`)**: Health, preventive medicine, physical fitness, sleep, meditation, well-being, personal hobbies, and disconnecting. -2. **🏡 Home (`HOME`)**: Housing, indoor/outdoor maintenance, gardening, repairs, groceries, meals, pets, kids, and family logistics. -3. **đŸ’Œ Work (`WORK`)**: Professional activities, project management, meetings, taxes/accounting, clients, quotes, contracts, and strategy. +Applications leveraging the kernel's cognitive assistance implement a Two-Tier hybrid model ensuring high availability, zero latency, and graceful offline degradation: ---- - -## ⚡ 4. Two-Tier Hybrid Architecture +```mermaid +flowchart TD + Input[User Text Input] --> Tier1[Tier 1: Local Heuristic Engine] + Tier1 -->|< 5ms Latency| FastUI[Instant Suggestion Rendered] + Input -->|Debounce 400ms| Tier2[Tier 2: Cloud LLM / Gemini API] + Tier2 -->|App Check OK| RefinedUI[Enriched Rationale & Confidence] + Tier2 -->|Network Error / 403| Graceful[Silent Fallback: Keep Tier 1 Suggestion] +``` -1. **Tier 1 — Local Heuristics (`< 5ms`)**: - * Instant synchronous deterministic analysis with 0 ms network latency. - * Strict Unicode tokenization (`\p{L}`) natively handling accented characters without substring false positives. - * Immediately suggests the Quadrant and Area of Life. +### Tier 1 — Local Deterministic Classifier (`< 5ms`) +* **Instant Feedback**: Executes synchronously on the main/background thread with 0 ms network overhead. +* **Deterministic Tokenization**: Strict Unicode boundary matching (`\p{L}`) handling accents and multilingual tokens without substring false positives. +* **Guaranteed Fallback**: Always provides an initial category/priority recommendation regardless of connectivity. -2. **Tier 2 — Gemini 3.5 Flash-Lite via Firebase AI Logic (Asynchronous)**: - * Triggered after typing stops (400ms debounce) or on focus loss. - * Uses `gemini-3.5-flash-lite` via `com.google.firebase:firebase-ai` with App Check (Play Integrity in production, `DebugAppCheckProvider` on emulator). - * Evaluates cognitive complexity, refines life area (`HOME`, `WORK`, `SELF`), enriches benevolent rationale, and tunes confidence. - * **Emulator App Check Resilience**: If debug tokens are not whitelisted in local environments, 403 errors are caught without polluting Crashlytics, and Tier 1 heuristics guarantee uninterrupted, instant classification. +### Tier 2 — Cloud LLM Inference (Gemini Flash via Firebase AI Logic) +* **Asynchronous Deep Reasoning**: Triggered with debounce (e.g., 400ms after user pauses typing or loses focus). +* **Structured Output Parsing**: Enforces strict schema validation (JSON / Type-safe response) to prevent hallucinated keys or unparseable payloads. +* **App Check Security**: Enforces Play Integrity in production and debug providers in local test environments. +* **Resilience Guarantee**: If network fails, API limits are reached, or App Check returns HTTP 403 on emulators, errors are intercepted cleanly. The Tier 1 local suggestion remains active, and Crashlytics is not spammed. --- -## 📋 5. Complete Test Matrix (All 12 Combinations) - -This table provides the canonical test phrases used to validate all 12 combinations in the input interface (`AddMentalLoadScreen.kt` and `EditMentalLoadSheet.kt`). +## 📋 4. Archetype AI Suggestion & Multi-Category Test Protocol -### 🧘 Area: For Self (`SELF`) +Rather than testing arbitrary domain strings, QA suites should validate the **Architectural Qualification Grid** covering the full permutation of categories and priority tiers: -| # | Expected Quadrant | Test Phrase (Copy-Paste) | Triggers / Rationale | -|:---:|---|---|---| -| **1** | ⚡ **Do Today** | `Prendre mes antibiotiques et appeler mĂ©decin en urgence aujourd'hui` | `urgence`, `aujourd'hui` + `santĂ©`, `mĂ©decin` | -| **2** | 🌿 **Schedule & Align** | `Prendre rendez-vous bilan de santĂ© mĂ©decin` *(or `Prendre du temps pour moi`)* | `santĂ©`, `mĂ©decin`, `rdv`, `temps pour moi` (no urgency marker) | -| **3** | đŸ€ **Duo Teamwork** | `Demander Ă  Sam de passer Ă  la pharmacie chercher mon ordonnance` | `demander Ă  Sam` + `pharmacie`, `ordonnance` | -| **4** | 🍃 **Park in Sanctuary** | `IdĂ©e pour plus tard : tester le yoga aĂ©rien un jour` | `idĂ©e pour plus tard`, `un jour` + `yoga` | +| Dimension | Qualification Criteria | Expected Engine Behavior | +|---|---|---| +| **Urgent & High Impact** | Immediate deadline, high-risk consequence, crisis action. | Tier 1 & Tier 2 converge on highest immediate priority tier. | +| **Important & Strategic** | Long-term planning, foundational projects, preventive actions. | Classified as scheduled/deliberate action without panic markers. | +| **Collaborative / Shared** | Explicit mention of collaborator, delegation, or joint responsibility. | Routed to shared/collaborative workspace or partner suggestion. | +| **Low-Urgency / Backlog** | Exploratory thoughts, wishlists, future ideas (*"someday-maybe"*). | Parked in low-priority sanctuary/backlog without deadlines. | ---- +### Golden Test Dataset Pattern +Deterministic unit tests validate the classification engine using parameterized golden datasets: -### 🏡 Area: Home (`HOME`) +```kotlin +@Test +fun verifyCategoryAndPriorityPermutations() { + // Assert all permutations of category and priority tiers map correctly + // across both Tier 1 heuristic triggers and Tier 2 structured responses. +} +``` -| # | Expected Quadrant | Test Phrase (Copy-Paste) | Triggers / Rationale | -|:---:|---|---|---| -| **5** | ⚡ **Do Today** | `Sortir les poubelles et rĂ©parer la fuite d'eau ce soir urgent` | `urgent`, `ce soir` + `poubelles`, `fuite`, `eau` | -| **6** | 🌿 **Schedule & Align** | `Tailler la haie et tondre la pelouse ce week-end` | `tailler`, `haie`, `tondre`, `pelouse` | -| **7** | đŸ€ **Duo Teamwork** | `Demander Ă  Sam de faire les courses et acheter du lait` | `demander Ă  Sam` + `courses`, `lait` | -| **8** | 🍃 **Park in Sanctuary** | `IdĂ©e pour plus tard : crĂ©er un potager dans le jardin` | `idĂ©e pour plus tard` + `jardin`, `potager` | +### Roborazzi Visual Regression UI States +Visual snapshot tests must capture the 4 canonical states of AI-assisted entry surfaces: +1. **Empty / Default State**: Unfocused input with placeholder. +2. **Typing / Tier 1 Fast State**: Instant suggestion chip displayed under input. +3. **Tier 2 Enriched State**: Refined suggestion with rationale and confidence indicator. +4. **Offline / Error Fallback**: Clean UI maintaining Tier 1 suggestion with zero error dialogs. --- -### đŸ’Œ Area: Work (`WORK`) +## đŸ§Ș 5. Automated Testing Execution & CI Verification -| # | Expected Quadrant | Test Phrase (Copy-Paste) | Triggers / Rationale | -|:---:|---|---|---| -| **9** | ⚡ **Do Today** | `DĂ©claration impĂŽts urgente aujourd'hui avant 18h` | `urgente`, `aujourd'hui`, `avant 18h` + `impĂŽts`, `dĂ©claration` | -| **10** | 🌿 **Schedule & Align** | `PrĂ©parer la roadmap stratĂ©gique du projet Q4` | `roadmap`, `stratĂ©gique`, `projet`, `q4` | -| **11** | đŸ€ **Duo Teamwork** | `Demander Ă  Sam de relire le devis et le contrat` | `demander Ă  Sam` + `devis`, `contrat` | -| **12** | 🍃 **Park in Sanctuary** | `IdĂ©e pour plus tard : explorer un projet open source un jour` | `idĂ©e pour plus tard`, `explorer`, `un jour` + `projet` | - ---- +Run the complete verification pipeline locally: -## đŸ§Ș 6. Automated Verification +```bash +# 1. Run unit test suite +./gradlew testDebugUnitTest --tests "*ClassifierTest*" -The unit test suite validates all of these rules: +# 2. Run full quality airbag (Lint, compilation, tests) +./scripts/quality-check.sh -```bash -./gradlew testDebugUnitTest --tests com.secondbrain.app.data.classifier.HeuristicTaskClassifierTest +# 3. Validate documentation contracts and byte budgets +./scripts/validate-docs.sh ``` - -Validated test: `verify all 12 combinations of AreaOfLife and PriorityQuadrant` in `HeuristicTaskClassifierTest.kt`.