@adaptic/maestro 1.0.0

package/docs/governance/action-approval-model.md

@@ -0,0 +1,331 @@
+# Action Approval Model
+
+This document defines the action approval framework for sophie-ai. It governs what the system may do autonomously, what requires human review, and what is categorically forbidden without explicit approval. The foundational principle is **default-deny**: any action not explicitly classified and approved in this framework is blocked.
+
+---
+
+## 1. Action Classification Taxonomy
+
+Every action the system takes falls into exactly one of five classes, ordered by increasing autonomy risk.
+
+| Class                | Code  | Description                                                                    | System Authority              |
+| -------------------- | ----- | ------------------------------------------------------------------------------ | ----------------------------- |
+| **Observe**          | `OBS` | Read, monitor, collect, summarize. No side effects.                            | Full autonomy                 |
+| **Draft**            | `DRF` | Create content in a staging area. Nothing is sent or published.                | Full autonomy                 |
+| **Recommend**        | `REC` | Present a recommendation to a human with supporting evidence. No action taken. | Full autonomy                 |
+| **Request Approval** | `REQ` | Propose a specific action and block until a human approves or rejects.         | Blocked until approved        |
+| **Execute**          | `EXE` | Carry out an approved or pre-authorized action that has external side effects. | Only with prior authorization |
+
+### Classification Rules
+
+1. If an action reads state without modifying it, it is `OBS`.
+2. If an action creates an artifact that is not yet visible to anyone outside the system, it is `DRF`.
+3. If an action surfaces options or analysis for human decision-making, it is `REC`.
+4. If an action requires a human to say "yes" before the system proceeds, it is `REQ`.
+5. If an action changes external state (sends a message, modifies a file, triggers an API call), it is `EXE`.
+
+---
+
+## 2. Risk Levels
+
+Each action is assigned a risk level based on reversibility, audience exposure, and potential for harm.
+
+| Risk Level   | Criteria                                                                                   | Examples                                                                                                                                              |
+| ------------ | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Low**      | Fully reversible, internal only, no external visibility                                    | Reading Slack messages, summarizing email threads, browsing internal docs                                                                             |
+| **Medium**   | Partially reversible, limited audience, minor external visibility                          | Drafting a Slack message to an internal team channel, creating a calendar event, editing a local file                                                 |
+| **High**     | Difficult to reverse, external audience, reputational or financial implications            | Sending email to an external partner, posting in a public Slack channel, committing code to a shared repository                                       |
+| **Critical** | Irreversible or near-irreversible, broad audience, legal/financial/regulatory implications | Sending communication to investors or regulators, executing financial transactions, modifying production infrastructure, publishing public statements |
+
+---
+
+## 3. Approval Chains
+
+Each risk level maps to a specific approval chain. Approval chains define who must approve and how.
+
+### Low Risk
+
+| Step | Actor  | Action                     |
+| ---- | ------ | -------------------------- |
+| 1    | System | Executes autonomously      |
+| 2    | System | Logs action to audit trail |
+
+No human approval required. System proceeds and logs.
+
+### Medium Risk
+
+| Step | Actor  | Action                                               |
+| ---- | ------ | ---------------------------------------------------- |
+| 1    | System | Drafts proposed action                               |
+| 2    | System | Presents draft to Sophie for review via notification |
+| 3    | Sophie | Approves, modifies, or rejects                       |
+| 4    | System | Executes if approved; logs outcome                   |
+
+Approval timeout: if no response within **4 hours**, the action is auto-rejected and Sophie is notified.
+
+### High Risk
+
+| Step | Actor  | Action                                                         |
+| ---- | ------ | -------------------------------------------------------------- |
+| 1    | System | Drafts proposed action with risk assessment                    |
+| 2    | System | Presents draft to Sophie with explicit risk summary            |
+| 3    | Sophie | Reviews and approves, modifies, or rejects                     |
+| 4    | System | Requires explicit confirmation (not just absence of rejection) |
+| 5    | System | Executes if confirmed; logs full decision chain                |
+
+Approval timeout: if no response within **2 hours**, the action is auto-rejected and escalated.
+
+### Critical Risk
+
+| Step | Actor  | Action                                                                           |
+| ---- | ------ | -------------------------------------------------------------------------------- |
+| 1    | System | Drafts proposed action with full risk assessment and legal/compliance flags      |
+| 2    | System | Presents to Sophie with mandatory review checklist                               |
+| 3    | Sophie | Reviews, completes checklist, and explicitly approves                            |
+| 4    | System | Requires typed confirmation phrase (e.g., "APPROVED: send investor update")      |
+| 5    | System | Waits for a **cooling-off period of 15 minutes** after approval before executing |
+| 6    | System | Sends a final confirmation prompt before execution                               |
+| 7    | System | Executes if re-confirmed; logs entire chain with timestamps                      |
+
+Approval timeout: **1 hour**. No auto-execute under any circumstances.
+
+---
+
+## 4. Per-Channel Policies
+
+### Slack
+
+| Action                                                       | Risk Level    | Approval Required |
+| ------------------------------------------------------------ | ------------- | ----------------- |
+| Read messages in any channel                                 | Low           | No                |
+| Summarize threads                                            | Low           | No                |
+| Draft message (not sent)                                     | Low           | No                |
+| Send message to `#sophie-ai-logs` or `#system-notifications` | Low           | No                |
+| Send message to internal team channel as Sophie-bot          | Medium        | Yes               |
+| Send message to shared channel with external partners        | High          | Yes               |
+| Send DM to any person as Sophie or Mehran                    | High          | Yes               |
+| Send message to `#general` or any all-hands channel          | High          | Yes               |
+| Create or archive a channel                                  | Critical      | Yes               |
+| Modify workspace settings                                    | **Forbidden** | N/A               |
+
+### Email (Gmail)
+
+| Action                                             | Risk Level    | Approval Required |
+| -------------------------------------------------- | ------------- | ----------------- |
+| Read emails                                        | Low           | No                |
+| Summarize inbox or threads                         | Low           | No                |
+| Draft email (saved to drafts, not sent)            | Low           | No                |
+| Send email to internal team member                 | Medium        | Yes               |
+| Send email to known external contact               | High          | Yes               |
+| Send email to investor, board member, or regulator | Critical      | Yes               |
+| Send email to unknown or new recipient             | Critical      | Yes               |
+| Delete emails                                      | **Forbidden** | N/A               |
+| Modify email filters or forwarding rules           | **Forbidden** | N/A               |
+
+### WhatsApp
+
+| Action                                   | Risk Level    | Approval Required |
+| ---------------------------------------- | ------------- | ----------------- |
+| Read messages                            | Low           | No                |
+| Summarize conversations                  | Low           | No                |
+| Draft reply (not sent)                   | Low           | No                |
+| Send message to internal team member     | Medium        | Yes               |
+| Send message to any external contact     | High          | Yes               |
+| Send message to investor or board member | Critical      | Yes               |
+| Send message to unknown number           | **Forbidden** | N/A               |
+
+### Browser
+
+| Action                                      | Risk Level    | Approval Required |
+| ------------------------------------------- | ------------- | ----------------- |
+| Open URLs and read web pages                | Low           | No                |
+| Search the web                              | Low           | No                |
+| Fill out internal tool forms (staging only) | Medium        | Yes               |
+| Submit forms on external websites           | High          | Yes               |
+| Authenticate or log in to any service       | Critical      | Yes               |
+| Access banking or financial platforms       | **Forbidden** | N/A               |
+
+### File System
+
+| Action                                                    | Risk Level    | Approval Required |
+| --------------------------------------------------------- | ------------- | ----------------- |
+| Read files in the sophie-ai directory                     | Low           | No                |
+| Read files outside sophie-ai (within home directory)      | Low           | No                |
+| Create or edit files in sophie-ai working directories     | Low           | No                |
+| Create or edit files outside sophie-ai                    | Medium        | Yes               |
+| Delete files in sophie-ai                                 | Medium        | Yes               |
+| Delete files outside sophie-ai                            | High          | Yes               |
+| Modify system files or dotfiles                           | **Forbidden** | N/A               |
+| Access `/etc`, `/usr`, or any system directory for writes | **Forbidden** | N/A               |
+
+### Git
+
+| Action                                         | Risk Level    | Approval Required |
+| ---------------------------------------------- | ------------- | ----------------- |
+| `git status`, `git log`, `git diff`            | Low           | No                |
+| `git add` and `git commit` on sophie-ai repo   | Low           | No                |
+| `git push` to sophie-ai repo (non-main branch) | Medium        | Yes               |
+| `git push` to sophie-ai repo (main branch)     | High          | Yes               |
+| `git push` to any other repository             | High          | Yes               |
+| `git push --force` to any repository           | **Forbidden** | N/A               |
+| Modify `.gitconfig` or SSH keys                | **Forbidden** | N/A               |
+
+---
+
+## 5. Per-Audience Policies
+
+The audience of an action independently modifies its risk level. If the channel policy says Medium but the audience policy says High, the **higher** risk level applies.
+
+| Audience                                           | Base Risk Modifier      | Notes                                                                   |
+| -------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------- |
+| **Internal team** (employees, contractors)         | No modifier             | Standard channel risk applies                                           |
+| **External partners** (known, active relationship) | +1 level (minimum High) | All external communication is at least High risk                        |
+| **Investors**                                      | Always Critical         | Every investor-facing communication requires full approval chain        |
+| **Regulators**                                     | Always Critical         | Regulatory communications require legal review flag                     |
+| **Board members**                                  | Always Critical         | Board communications require full approval chain                        |
+| **Media**                                          | Always Critical         | No media communication without explicit approval and cooling-off period |
+| **Unknown / Unclassified**                         | Always Critical         | Default-deny applies; unknown audience is treated as maximum risk       |
+
+---
+
+## 6. Emergency Stop Procedures
+
+### Immediate Halt Triggers
+
+The system must immediately halt all pending and in-progress actions if any of the following occur:
+
+1. **Sophie issues a stop command** via any monitored channel (Slack, terminal, WhatsApp) containing the phrase: `STOP ALL`, `EMERGENCY STOP`, or `HALT`
+2. **System detects anomalous behavior**: more than 5 failed actions in 60 seconds, unexpected UI state 3 times consecutively, or any unhandled exception in the execution pipeline
+3. **Network or authentication failure**: if the system loses access to a required service mid-operation, all pending actions for that service are suspended
+4. **Rate limit breach**: if any rate limit defined in the desktop control safety framework is exceeded
+
+### Halt Procedure
+
+1. Cancel all pending approval requests (mark as "halted, not rejected")
+2. Abort all in-progress executions at the nearest safe checkpoint
+3. Log the halt event with timestamp, trigger reason, and list of affected actions
+4. Send notification to Sophie via the most reliable available channel
+5. Enter **safe mode**: only `OBS` class actions permitted until Sophie explicitly resumes operations
+6. Resume requires Sophie to issue: `RESUME OPERATIONS` with optional scope restrictions
+
+---
+
+## 7. Override Mechanisms
+
+### Sophie Override
+
+Sophie can override any policy in this document by providing an explicit, specific override instruction. Overrides must:
+
+1. Name the specific policy being overridden (e.g., "Override: send email to investor without cooling-off period")
+2. Be issued in a monitored channel with audit logging
+3. Be logged as an override event with full context
+4. Apply to a **single action only** — overrides do not create precedent or modify standing policy
+5. Expire after the action is completed or after 1 hour, whichever comes first
+
+### Mehran Override
+
+Mehran can override any policy by providing instruction through a monitored channel. The same rules as Sophie Override apply. Mehran overrides are logged separately and flagged for Sophie's review within 24 hours.
+
+### Standing Exceptions
+
+Recurring overrides for the same action type should be formalized as standing exceptions:
+
+1. Documented in this file under a "Standing Exceptions" appendix
+2. Reviewed monthly
+3. Each exception has an expiration date (maximum 90 days)
+4. Expired exceptions revert to default policy
+
+---
+
+## 8. Audit Trail Requirements
+
+Every action the system takes — regardless of class or risk level — must be logged.
+
+### Required Fields
+
+| Field            | Description                                  | Required For        |
+| ---------------- | -------------------------------------------- | ------------------- |
+| `timestamp`      | ISO 8601 timestamp of the action             | All actions         |
+| `action_class`   | OBS, DRF, REC, REQ, EXE                      | All actions         |
+| `risk_level`     | Low, Medium, High, Critical                  | All actions         |
+| `channel`        | The channel or system involved               | All actions         |
+| `audience`       | The audience classification                  | EXE actions         |
+| `description`    | Human-readable description of what was done  | All actions         |
+| `content_hash`   | SHA-256 hash of the content sent or modified | EXE actions         |
+| `approval_chain` | Full record of who approved, when, and how   | REQ and EXE actions |
+| `override_flag`  | Whether any override was used                | All actions         |
+| `outcome`        | Success, failure, halted, rejected           | All actions         |
+| `error_detail`   | Error message and stack trace if applicable  | Failed actions      |
+| `duration_ms`    | Time taken to complete the action            | All actions         |
+
+### Retention
+
+- All audit logs are retained for a minimum of **1 year**.
+- Critical-risk action logs are retained for a minimum of **3 years**.
+- Logs are stored in `/Users/sophie/sophie-ai/logs/audit/` with daily rotation.
+- Logs must not be modified or deleted by the system. Only manual human intervention may alter log files.
+
+---
+
+## 9. Specific Examples
+
+### Low Risk Examples
+
+- Reading the latest 50 messages in `#engineering` on Slack
+- Summarizing Sophie's email inbox for the morning briefing
+- Checking the status of a GitHub pull request
+- Reading a file in `sophie-ai/data/`
+
+### Medium Risk Examples
+
+- Sending a message to `#team-updates` on Slack: "Sophie's morning priorities: [list]"
+- Creating a calendar event for an internal team meeting
+- Editing a draft document in Google Docs (internal)
+- Pushing a branch to the sophie-ai repository
+
+### High Risk Examples
+
+- Sending an email to a partner company about a project timeline
+- Posting a message in a shared Slack channel with an external vendor
+- Committing and pushing to the main branch of the sophie-ai repo
+- Sending a WhatsApp message to an external collaborator
+
+### Critical Risk Examples
+
+- Sending a quarterly update email to investors
+- Responding to a regulatory inquiry via email
+- Sending any communication to a board member
+- Publishing a blog post or public statement
+- Submitting a form on a government or regulatory website
+
+---
+
+## 10. Default-Deny Principle
+
+**Any action not explicitly classified in this document is denied by default.**
+
+This means:
+
+1. If a new channel, application, or audience is encountered that is not listed in the per-channel or per-audience policies, the system must treat it as **Critical risk** and require full approval.
+2. If the system is uncertain about the classification of an action, it must default to **REQ** (Request Approval) with the highest applicable risk level.
+3. New action types must be formally added to this document before they can be executed autonomously.
+4. The system must never infer that a missing policy implies permission. Silence means denial.
+5. If the system encounters an action that spans multiple channels or audiences, the **most restrictive** policy applies.
+
+---
+
+## Appendix A: Standing Exceptions
+
+_No standing exceptions are currently active._
+
+| Exception ID | Action Description | Override Scope | Approved By | Effective Date | Expiration Date |
+| ------------ | ------------------ | -------------- | ----------- | -------------- | --------------- |
+| —            | —                  | —              | —           | —              | —               |
+
+---
+
+## Appendix B: Change Log
+
+| Date       | Author                 | Change Description        |
+| ---------- | ---------------------- | ------------------------- |
+| 2026-04-02 | Sophie (via sophie-ai) | Initial framework created |