Skip to content

GOVERNANCE.md

Latest commit

 

History

History
159 lines (114 loc) · 5.94 KB

GOVERNANCE.md

File metadata and controls

159 lines (114 loc) · 5.94 KB

Agent Governance Document

Hidden Opportunities Agent — Autonomy Limits & Escalation Rules

Version: 1.0
Created: Sprint 3 (2026-04-11)
Owner: Agency Leadership
Review cadence: Every sprint (2 weeks)

Purpose

This document defines the boundaries of autonomous action the Hidden Opportunities Agent is authorized to take without human approval. It exists to:

  1. Build trust with clients and the agency team.
  2. Prevent the agent from taking irreversible actions outside its mandate.
  3. Provide an audit trail for every automated decision.
  4. Serve as the reference document for engineering when implementing Sprint 4+.

Autonomy Tiers

The agent operates in one of three tiers depending on the opportunity type, confidence score, and proposal value.

Tier Condition Agent Action Human Required?
A — Full Human Control Any proposal Generate draft only Yes — approve before send
B — Human Approval Required Score 70–89 OR value > $200 Generate + notify Yes — Slack approve/reject
C — Autonomous Send Score ≥ 90 AND value ≤ $200 AND client is repeat buyer Generate + send + BCC No (Sprint 4+)

Sprint 3 status: Only Tier A is implemented. The agent generates proposals and saves them as drafts. No email is sent without explicit human approval via the Proposals UI or a Slack /approve command.

Sprint 4 target: Tier C will be enabled for reactivation opportunities with score ≥ 90 and value ≤ $150, with a 24-hour delay that allows cancellation.

What the Agent Can Do Autonomously (Sprint 3)

  • Detect upsell/cross-sell opportunities using the rule engine (daily).
  • Generate a personalized proposal draft using an LLM.
  • Save the draft to the database and export it as a Markdown file.
  • Notify the account manager via Slack (in production) with the proposal link.

What the Agent Cannot Do Without Approval

  • Send any email to a client (all sends require explicit approval).
  • Modify client data in the CRM (read-only in all sprints).
  • Make financial commitments (discounts, payment arrangements).
  • Close a sale or issue an invoice without human confirmation.
  • Contact a client more than once for the same opportunity in a 30-day window.

Escalation Rules

The agent must immediately escalate to a human (account manager + team lead) in any of the following situations:

Trigger Action
Client explicitly says "cancel", "stop", or "unsubscribe" Halt all communications, flag in CRM
Client expresses strong negative sentiment (anger, complaint) Escalate to account manager within 5 minutes
Proposal value > $500 Always require C-level approval
Client requests more than 20% discount Escalate — agent cannot authorize
Same client, same opportunity, 3+ rejected proposals Pause and notify account manager
System error during email send Log, notify, and do NOT retry automatically
Opportunity score drops > 30 points since last run Flag for human review

Audit Log Requirements

Every autonomous action must be logged with:

  • Timestamp (ISO 8601, UTC)
  • Agent version (git commit hash)
  • Action type (generate_proposal, send_email, update_status)
  • Opportunity ID and Proposal ID
  • Client ID (anonymized in exports)
  • Decision basis (rule that fired, score, LLM model used)
  • Human approval (approved_by, timestamp if applicable)

Logs are stored in:

  • Demo: logs/proposals.jsonl (append-only)
  • Production: HubSpot CRM activity log + S3 audit bucket (90-day retention)

Thresholds Reference

These are the current autonomous-action thresholds. Any change requires a pull request + team lead sign-off.

# Confidence thresholds
MIN_SCORE_FOR_PROPOSAL_GENERATION   = 70    # Score 0–100
MIN_SCORE_FOR_TIER_C_AUTONOMY       = 90    # Sprint 4+
MAX_VALUE_FOR_TIER_C_AUTONOMY       = 200   # USD

# Contact limits
MAX_PROPOSALS_PER_CLIENT_PER_30DAYS = 2
MIN_DAYS_BETWEEN_SAME_OPPORTUNITY   = 30

# Discount limits (Sprint 7)
MAX_AUTONOMOUS_DISCOUNT_PCT         = 15    # % off suggested price
MAX_AUTONOMOUS_DISCOUNT_USD         = 100   # absolute cap regardless of %

# Escalation triggers
NEGATIVE_SCORE_CHANGE_THRESHOLD     = 30    # score drop that triggers review
MAX_REJECTED_PROPOSALS_BEFORE_PAUSE = 3

Client Consent

Before the agent contacts any client autonomously (Sprint 4+):

  1. The client must have opted in to "digital marketing automation" in the service agreement (standard clause added from Sprint 4 onward).
  2. Every automated email must include:
    • Clear identification that it was generated by an AI agent.
    • A one-click opt-out link that immediately pauses all agent activity.
  3. The opt-out is processed within 24 hours (target: immediately).

Prohibited Actions — Hard Limits

These actions are hard-coded off and cannot be enabled via configuration:

  • Sending emails to anyone not in the agency CRM.
  • Accessing client financial accounts or payment instruments.
  • Impersonating a human account manager without disclosure.
  • Storing client data outside the approved databases (SQLite/Supabase).
  • Sharing client metrics with third-party services except the configured LLM providers (data is anonymized before LLM calls in production).

Review and Change Process

  1. Changes to autonomy thresholds → pull request + review by agency lead.
  2. Changes to escalation rules → pull request + review by account manager team.
  3. Changes to prohibited actions → requires written sign-off from two senior partners.
  4. This document is version-controlled in the same repository as the agent code. Changes are logged in git history.

This governance document doubles as demo documentation for stakeholder presentations. Reviewers should note that in the current demo environment, no real emails are sent and all client data is synthetic.