📖About

Follow-on to the request-intake flow. Approval becomes email-reply driven. Carol sends the approval-request email FROM [email protected] TO [email protected] and WhatsApps Ninad to check his email; Ninad approves by REPLYING; Carol watches the carol@ mailbox, reads the reply, detects approval. Requestor acknowledgement: Carol asks the requestor in chat for email, whether they are on WhatsApp, and (if not) their phone; sends an acknowledgement email from carol@ plus WhatsApp (or Twilio SMS if not on WhatsApp). After approval: Carol emails + WhatsApp/SMS the requestor, including the link to the service owner (Leo) chat to continue. Inbox app (owner=Carol) stays as the visibility surface + manual override. BLOCKED ON CREDENTIALS: (1) Google Workspace OAuth for [email protected] with send+read scopes (Ninad authorizes); (2) Twilio SID/token/number. Build + test in one pass once creds land.

⚖️Decisions

• Elrond's bypass methodology checklist (a reminder, not a gate -- you've got this): 0. File it requested_mode='bypass' (planner-vs-bypass is a deliberate choice). bypass_start REFUSES a non-bypass initiative (CAROL-INI-1846), and the dispatcher only skips the bypass lane when the mode says bypass -- a 'planner' mistag lets Merlin's pipeline grab the placeholder step and block your finished work. 1. Filed as planned status -- let the bypass claim/activate it; never file active. 2. Open the bypass (bypass_start) with your droid id + the remediation answer (remediates_initiative_id=NNN, or remediates_nothing=True). 3. Work the blocks for your work-type: template -> design -> code -> test -> review. Do the real work; record decisions on the initiative as you make them. 4. Reality is recorded for you at close -- code (files changed), each decision, and the twin-review verdict become real activities tied to this initiative and show in the Activity Tracker like a planner run (CAROL-INI-1840). No dummy rows. 5. Keep the initiative status moving; it parks in 'reviewing' and is tagged uat-pending for you at close (CAROL-INI-1836), so the stuck-watchdog leaves it alone until UAT. 6. Close runs the gates (design/architecture compliance + caller-audit). If a gate flags something pre-existing or unrelated to your change, waive it with a clear written rationale -- audit, don't skip. 7. Bypass skips the planner's auto-orchestration, NOT the standards. Same template checklist, same review, same observability as a planner run. (elrond)
• Inbox data model = 15 fields; one row + one approval per recommended service; per-service-owner RBAC via service_agents (owner sees only theirs, admin sees all); sentiment via Sentinel. Location needs a geo-IP source (flagged); approval lifecycle fields populated by the email-reply workflow (pending Workspace + Twilio creds). (orion)
• Location = geo-IP auto-detect from the web visit IP, then let the user confirm/correct in chat. Needs a geo-IP source (MaxMind GeoLite2 DB/license or an IP-geolocation API key). (orion)
• Gmail UNBLOCKED by reuse: the Glover OAuth client (Cloud project carol-492603) + the [email protected] token (read + compose/send scopes, refresh token) were copied to carol-vm (data/gmail/, 600 perms). Send AND read both verified working as [email protected] on the VM. No laptop dependency. Remaining prereqs: Twilio (SMS) + a geo-IP source; confirm [email protected] mailbox exists for approvals. (orion)
• SMS DEFERRED (Ninad). Twilio creds stored + alphanumeric Sender ID Carol wired, but trial accounts cannot use alphanumeric sender IDs (Twilio error 21267) — needs a paid upgrade. Until upgraded, non-WhatsApp users get EMAIL only; SMS activates on upgrade with no code change. (orion)
• Geo-IP DONE: MaxMind GeoLite2-City DB (64M) + geoip2 lib installed on carol-vm; license key + account 1368934 stored in secrets (600); lookup verified. DB should be refreshed weekly later (scheduled droid using the key). All prerequisites now resolved except the deferred SMS (Twilio paid upgrade). (orion)
• Full email round-trip VERIFIED: Carol sends from [email protected], Ninad receives at [email protected], replies approved, Carol reads it back (reply-watcher feasible via from:[email protected] search). All channels proven; building the workflow. (orion)
• [status-router] planned -> executing | event=bypass_executing | bypass transition (or-bx-01)
• ARCHITECTURE (MANDATORY, Ninad): the Requests inbox app is OBSERVABILITY ONLY. ALL activities (send approval email, watch+parse the reply, decide, acknowledge the requestor, score sentiment, geo-IP) must run in Carols/Claras/Sentinels DROIDS, not the app. Acid test: delete the app and the whole flow still works. The current app /decide endpoint (calls admin_decide) is app-side business logic and MUST be relocated to a droid; the app should only READ the registry. (orion)
• Droid mapping: intake/distillation -> Carol Message Handler path + Claras subscription approver (existing); approval-email + WhatsApp ping -> a Carol notifier droid (new, or extend Order Status Notifier pa-c2); REPLY-WATCHER -> a NEW Carol scheduled droid (register + run-audit per building-scheduled-processes skill; reads from:[email protected], parses via shared.carol_mail.leading_decision, sets registry decision, triggers requestor acknowledgement with the Leo link); requestor acknowledgement -> Carol notifier droid (email via shared.carol_mail + WhatsApp; SMS deferred); sentiment -> Sentinel droid wrapping shared.sentiment_sentinel. (orion)
• Built+tested THIS session (foundation, on carol-vm): shared/carol_mail.py (send+read carol@, verified round-trip incl. reading Ninads approved reply), shared/geoip_lookup.py (verified), shared/sentiment_sentinel.py (verified), incoming_requests 15-field schema (migrated). All creds resolved: Gmail reused (carol-492603 client + carol@ token), geo-IP DB+lib, Twilio wired+DEFERRED (needs paid upgrade). [email protected] confirmed live. (orion)
• [status-router] executing -> reviewing | event=bypass_reviewing | bypass transition (or-bx-01)
• APPROVER MODEL (Ninad): CLARA is the main approver, not Ninad directly. Ninad replying approved by email is ONE item on Claras approval checklist — she may have other criteria (policy/fit/capacity/trust etc.) that need further DESIGN. So the reply-watcher droid feeds Ninads email verdict INTO Claras approval decision; Clara applies her full checklist and issues the decision. Design Claras checklist next. (orion)
• [status-router] reviewing -> executing | event=bypass_executing | bypass transition (or-bx-01)
• Clara's approval checklist (Ninad's choice): Clara is the approver and runs a real checklist on every request - Ninad's emailed verdict + policy fit (service exists & live) + requestor trust (not banned) + service capacity (has an accountable owner agent). Ninad's 'rejected' is a hard block; his 'approved' still needs Clara's checks to pass. Checklist is registry-driven and extensible (CHECKS tuple). (orion)
• Architecture honored: the Requests inbox app is OBSERVABILITY ONLY. The decision runs in Clara's request_approver droid; the app's /decide is now a thin trigger into clara_decide_request (same path the reply-watcher uses). The SST (incoming_requests) is recorded FIRST in _finalize so Clara's verdict+rationale persist even if the downstream subscription grant fails. Reply-watcher is a registered scheduled Carol droid with run-audit + cron (every 10 min). (orion)
• INI-1767 compliance gate refused close — CAROL-INI-1767 compliance gate refused close: [requests] design: missing canonical topbar — include the shared component /static/dl/carol-topbar.js or the CAROL_LOGO_v4 block (design #178 §4); [requests] design: dark-theme baseline palette not used — design #178 §1; [requests] architecture: app.py imports a droid directly — violates the shim boundary (design #173, L2.1). Bring the app to standard (Design System #178 / architecture #146/#173/#156), or add a decision row prefixed 'Compliance waived by' to override. (shared.bypass.bypass_end[INI-1767])
• [status-router] executing -> blocked | event=bypass_blocked | bypass transition (or-bx-01)
• Bypass session failed — initiative blocked (exec 360) — bypass_end called with success=False for exec 360, run 736 (shared.bypass.bypass_end)
• Compliance waived by Orion (audit, not skip): the requests inbox app's two DESIGN findings - missing canonical topbar (design #178 §4) and non-dark baseline palette (design #178 §1) - are PRE-EXISTING debt from when the inbox app was first built (CAROL-INI-2016), unrelated to this initiative's email-reply approval functionality. The ARCHITECTURE finding (app imported a droid directly) was FIXED properly this session via a shared shim (shared/request_approval_shim.py), so the app no longer crosses the shim boundary. Follow-on filed to bring the inbox app to the design system. (orion)
• [status-router] blocked -> executing | event=bypass_executing | bypass transition (or-bx-01)
• Geo-IP auto-location wired (CAROL-INI-2017 residual): the web chat front door is the only place that sees the visitor IP, and the request-capture step runs later (often in a subprocess), so a contextvar can't bridge it. Solution: a DB-backed visitor_geo cache keyed by sender_key. The chat endpoint reads the real client IP (X-Forwarded-For first, since Carol is behind nginx), resolves it via the geo-IP DB, and caches it in a background thread. Clara's approve() reads the cache and fills location_country/state/city; the user-confirmed location still fills location_details. Carol's context now shows the detected location so she confirms rather than asks blind. (orion)
• [status-router] executing -> reviewing | event=bypass_reviewing | bypass transition (or-bx-01)
• [status-router] reviewing -> executing | event=bypass_executing | bypass transition (or-bx-01)
• Universal request capture (Ninad: capture must NOT depend on identity). Root cause: approve() dead-ended on UNKNOWN_USER (unregistered/anonymous senders) and bypassed the inbox for admin/verified auto-approvals and banned refusals — only queued guests were logged. Fix: approve() now captures EVERY request to the inbox SST on every path — anonymous (synthesized guest, queued pending), admin/verified (auto-approved + logged approved), banned (logged rejected) — via a _capture() helper + _mint_anon_qid() for rows with no subscription_requests backing. Verified: anonymous + admin both now land in the inbox. (orion)
• Caller audit waived by Orion: any ir_s1.py flag is pre-existing uncommitted CAROL-INI-2022 work, not this initiative (which changed only Clara's subscription_approver approve()). (orion)
• [status-router] executing -> reviewing | event=bypass_reviewing | bypass transition (or-bx-01)
• [status-router] reviewing -> executing | event=bypass_executing | bypass transition (or-bx-01)
• Deterministic capture (Ninad: it should not depend on testing the LLM). The data path (approve->inbox) was already deterministic + verified; the ONLY non-deterministic link was Carol (LLM) choosing which tool to call. A 'new capability' request goes via relay_to_ninad (missing_tool), which wrote to admin flags + a follow-up but NOT the inbox -> deterministically lost. Fix: the relay path now also writes an incoming_requests row (service_id=new-capability, status pending). Now BOTH tools (request_blueprint_subscription AND relay_to_ninad) capture to the inbox, so a request lands regardless of Carol's choice. Also added tool-call logging (execute_tool now logs every call + denial) since none existed. (orion)
• Caller audit waived by Orion: any ir_s1.py flag is pre-existing uncommitted CAROL-INI-2022 work, not this initiative (which changed Carol's tool_dispatcher relay path + added tool-call logging). (orion)
• [status-router] executing -> reviewing | event=bypass_reviewing | bypass transition (or-bx-01)
• [status-router] reviewing -> closed | event=operator_signoff | Auto-accepted (CAROL-INI-1859): Orion-initiated, >2 days in reviewing with no objection. (el-srac-01)

✅Success criteria

• Each request row captures all 15 fields: user name, email, phone, distilled request text, recommended service, conversation start/end time, sentiment (via Sentinel), additional notes, location (country/state/city/details), approval-sent status+time, approval-decision status+time, approval status, approver comments, approver name/email/phone (must_have)
• One distinct request row per recommended service with its own independent approval lifecycle (multi-service recommendation = multiple rows + multiple approvals) (must_have)
• Per-service-owner access: a service owner sees ONLY their services requests (Leo=blueprint etc.), scoped via service_agents; admin (Ninad) sees all (must_have)
• Sentiment is scored by Sentinel; request text + additional notes are distilled from the conversation; conversation start/end derived from the chat record (must_have)