agent-enderun 0.7.2 → 0.7.5

package/.enderun/knowledge/corporate-governance/domain-error-handling-standard.md

@@ -0,0 +1,75 @@
+# Domain Error Handling & Typed Errors Standard
+
+**Applies to**: All backend and shared contract code in enterprise projects using Agent Enderun.
+
+## Purpose
+In large-scale corporate systems, generic `Error` or string-based error messages lead to fragile code, poor debugging, and insecure error handling. We enforce a typed, domain-aware error system.
+
+## Core Principles
+
+1. Every domain error must be represented by a dedicated class that extends a base `DomainError`.
+2. Errors must carry machine-readable codes, not just human messages.
+3. Errors must be serializable in a consistent, safe format for API responses.
+4. Never use `throw new Error("something went wrong")` in production business logic.
+
+## Standard Error Hierarchy
+
+```ts
+// apps/backend/src/types/errors.ts
+
+export abstract class DomainError extends Error {
+  abstract readonly code: string;
+  abstract readonly statusCode: number;
+  readonly details?: Record<string, unknown>;
+
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message);
+    this.details = details;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+
+  toJSON() {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        details: this.details,
+      },
+    };
+  }
+}
+
+// Example concrete errors
+export class UserNotFoundError extends DomainError {
+  readonly code = 'USER_NOT_FOUND';
+  readonly statusCode = 404;
+}
+
+export class InsufficientPermissionsError extends DomainError {
+  readonly code = 'INSUFFICIENT_PERMISSIONS';
+  readonly statusCode = 403;
+}
+
+export class HighRiskActionRequiresApprovalError extends DomainError {
+  readonly code = 'HIGH_RISK_ACTION_REQUIRES_APPROVAL';
+  readonly statusCode = 403;
+}
+```
+
+## Usage Rules
+
+- Business logic must throw specific domain errors, never generic ones.
+- API layer (Fastify error handler) converts `DomainError` instances into safe JSON responses.
+- Never expose stack traces or internal details to clients.
+- Frontend must be able to handle known error codes and show appropriate user-facing messages.
+
+## Integration with High-Risk Governance
+
+When a high-risk action is attempted without proper `managerApproval`, the backend **must** throw `HighRiskActionRequiresApprovalError`. This error code is then used by the frontend to trigger the security modal flow.
+
+## Enforcement
+
+- `@backend` must reject any implementation that uses raw `Error` or `throw new Error(...)` for domain cases.
+- `@analyst` will periodically scan for anti-patterns using static analysis.
+
+This standard ensures consistent, safe, and debuggable error handling across the entire system.

package/.enderun/knowledge/corporate-governance/frontend-high-risk-modal-guide.md

@@ -0,0 +1,211 @@
+# Security Modal + Hermes Briefing Component Implementation Guide (@frontend)
+
+**Applies to**: Any UI flow that can trigger high-risk administrative actions.
+
+**Goal**: Provide @frontend with a concrete, reusable, and governance-compliant pattern using Panda CSS and proper state management.
+
+---
+
+## 1. Component Architecture (Recommended)
+
+```
+apps/web/src/components/ui/
+├── HighRiskSecurityModal/
+│   ├── HighRiskSecurityModal.tsx
+│   ├── HighRiskSecurityModal.types.ts
+│   └── HighRiskSecurityModal.styles.ts   (Panda CSS)
+├── hooks/
+│   └── useHighRiskApproval.ts            (Hermes briefing logic)
+```
+
+---
+
+## 2. Core Types
+
+```ts
+// HighRiskSecurityModal.types.ts
+import { ManagerApproval, TraceID } from '../../../types/api-contracts';
+
+export interface HighRiskActionContext {
+  actionType: string;           // e.g. "PROMOTE_TO_SUPERADMIN"
+  targetId: string;
+  targetDescription: string;
+}
+
+export interface HighRiskApprovalResult {
+  approved: boolean;
+  managerApproval?: ManagerApproval;
+}
+```
+
+---
+
+## 3. Hook: useHighRiskApproval (Hermes Coordination)
+
+```ts
+// hooks/useHighRiskApproval.ts
+
+export function useHighRiskApproval() {
+  const [status, setStatus] = useState<'idle' | 'awaiting_manager' | 'approved' | 'rejected'>('idle');
+  const [approval, setApproval] = useState<ManagerApproval | null>(null);
+
+  const requestApproval = async (context: HighRiskActionContext, reason: string) => {
+    setStatus('awaiting_manager');
+
+    // In real implementation, this sends a Hermes message to @manager
+    const hermesMessage = {
+      type: 'high_risk_approval_request',
+      traceId: generateTraceId() as TraceID,
+      payload: {
+        action: context.actionType,
+        targetId: context.targetId,
+        reason,
+      },
+    };
+
+    // Simulated Hermes round-trip (in real system this would be async via MCP/tools)
+    const response = await sendHermesToManager(hermesMessage);
+
+    if (response.status === 'approved') {
+      setApproval(response.managerApproval);
+      setStatus('approved');
+      return { approved: true, managerApproval: response.managerApproval };
+    } else {
+      setStatus('rejected');
+      return { approved: false };
+    }
+  };
+
+  return { status, approval, requestApproval };
+}
+```
+
+---
+
+## 4. Security Modal Component (Panda CSS)
+
+```tsx
+// HighRiskSecurityModal.tsx
+
+import { css } from '../../../styled-system/css';
+
+interface Props {
+  isOpen: boolean;
+  context: HighRiskActionContext;
+  onClose: () => void;
+  onApproved: (approval: ManagerApproval) => void;
+}
+
+export function HighRiskSecurityModal({ isOpen, context, onClose, onApproved }: Props) {
+  const [reason, setReason] = useState('');
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const { status, approval, requestApproval } = useHighRiskApproval();
+
+  const handleRequestApproval = async () => {
+    if (!reason.trim()) return;
+
+    setIsSubmitting(true);
+    const result = await requestApproval(context, reason);
+
+    if (result.approved && result.managerApproval) {
+      onApproved(result.managerApproval);
+      onClose();
+    }
+    setIsSubmitting(false);
+  };
+
+  if (!isOpen) return null;
+
+  return (
+    <div className={css({ position: 'fixed', inset: 0, bg: 'rgba(0,0,0,0.7)', zIndex: 1000 })}>
+      <div className={css({
+        bg: 'white',
+        maxW: '480px',
+        mx: 'auto',
+        mt: '10vh',
+        p: '6',
+        borderRadius: 'lg',
+        border: '2px solid {colors.red.600}',
+      })}>
+        <h2 className={css({ color: 'red.600', fontSize: 'xl', fontWeight: 'bold' })}>
+          ⚠️ High-Risk Administrative Action
+        </h2>
+
+        <p className={css({ mt: 3 })}>
+          You are about to perform: <strong>{context.actionType}</strong><br />
+          Target: {context.targetDescription}
+        </p>
+
+        <label className={css({ display: 'block', mt: 4, fontWeight: 'medium' })}>
+          Reason for this action (required for audit and approval):
+        </label>
+        <textarea
+          value={reason}
+          onChange={(e) => setReason(e.target.value)}
+          className={css({ w: 'full', h: '100px', mt: 2, p: 3, border: '1px solid gray' })}
+          placeholder="Explain why this privileged action is necessary..."
+        />
+
+        <div className={css({ display: 'flex', gap: 3, mt: 5 })}>
+          <button onClick={onClose} disabled={isSubmitting}>
+            Cancel
+          </button>
+          <button
+            onClick={handleRequestApproval}
+            disabled={isSubmitting || !reason.trim()}
+            className={css({ bg: 'red.600', color: 'white' })}
+          >
+            {status === 'awaiting_manager' 
+              ? 'Waiting for @manager approval via Hermes...' 
+              : 'Request Manager Approval'}
+          </button>
+        </div>
+
+        <p className={css({ fontSize: 'xs', color: 'gray.500', mt: 4 })}>
+          This action will be fully audited. A valid managerApproval token is required.
+        </p>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## 5. Usage in a Page
+
+```tsx
+const handlePromoteClick = (user: User) => {
+  setSelectedUser(user);
+  setModalOpen(true);
+};
+
+const handleApproved = (approval: ManagerApproval) => {
+  // Now safe to call the high-risk API with the token
+  promoteUser(user.id, approval);
+};
+```
+
+---
+
+## 6. Anti-Patterns (Forbidden)
+
+- Calling high-risk API endpoints directly from event handlers
+- Generating fake `managerApproval` objects on the client
+- Making the modal dismissible while the Hermes request is in flight
+- Storing approval tokens in localStorage for later reuse
+- Skipping the “reason” field
+
+---
+
+## 7. Testing Requirements
+
+- Modal appears when high-risk action is triggered
+- API call is blocked until valid approval is received
+- Reason field is mandatory
+- Proper error states when @manager rejects the request
+
+**Reference files**:
+- `high-risk-security-modal-hermes-flow.md`
+- `high-risk-action-approval-flow-simulation.md`
+- `corporate-project-scaffolding-sop.md`

package/.enderun/knowledge/corporate-governance/governance-baseline-briefing-template.md

@@ -0,0 +1,54 @@
+# Governance Baseline Briefing Template (for @manager)
+
+**Use Case**: Use this as the foundation for the first major response when a user starts a new project that appears to be corporate or enterprise in nature.
+
+**Goal**: Establish the governance contract early, set expectations, and position the standards as non-negotiable enablers rather than obstacles.
+
+---
+
+## Template
+
+Thank you for initiating this project with Agent Enderun.
+
+Before we discuss any specific features, architecture, or technology choices, we must establish the governance baseline that will guide all work.
+
+### Corporate Governance Standards
+
+This project will follow Agent Enderun’s enterprise governance model. The three foundational pillars are:
+
+1. **Branded Types Law**  
+   All domain identifiers (UserID, RoleID, ApprovalID, etc.) must use compile-time branded types. Plain strings or numbers for identifiers are not permitted.
+
+2. **High-Risk Administrative Action Governance**  
+   Any operation that elevates roles, changes system configuration, performs bulk operations, or accesses sensitive audit data is classified as high-risk. These actions may only be executed after:
+   - Explicit `isHighRiskAdminAction: true` flag, and
+   - A valid `managerApproval` token containing a signed reason and trace ID.
+
+3. **Contract-First Development + Hermes Coordination**  
+   API contracts and type definitions are created before implementation. Any change to shared contracts must be communicated via Hermes to the relevant specialist agents.
+
+These standards exist to make the system auditable, safe, and maintainable at scale. They are not optional.
+
+### How We Will Work Together
+
+- We will **not** start by building features.
+- We will first define the type foundation and governance infrastructure.
+- Only after the foundation is in place will we proceed to implement user-facing functionality.
+- I (@manager) will personally review and approve the governance approach for any high-risk area before implementation begins.
+
+### Next Immediate Steps
+
+If you agree with this approach, please confirm. Once confirmed, we will begin with:
+
+1. Creation of the Branded Types foundation and core `ManagerApproval` contract.
+2. Definition of the first set of API contracts.
+3. (If privileged operations are expected) Design of the high-risk approval flow and security modal pattern.
+
+Would you like to proceed with this governance-first approach, or do you have any questions or concerns before we begin?
+
+---
+
+**Usage Notes for @manager**:
+- Adapt the language based on how much the user already understands.
+- If the user pushes back on governance, treat it as a signal to spend more time on education rather than proceeding faster.
+- Always document the user’s acknowledgment in `PROJECT_MEMORY.md` under Critical Decisions.

package/.enderun/knowledge/corporate-governance/high-risk-action-approval-flow-simulation.md

@@ -0,0 +1,167 @@
+# High-Risk Action Approval Flow Simulation
+
+**Purpose**: This simulation demonstrates the complete end-to-end flow of a high-risk administrative action in a corporate project, from the moment the user clicks the button in the UI until the action is executed and audited.
+
+**Scenario**: A company administrator wants to promote a regular user to SuperAdmin. This action is classified as high-risk.
+
+---
+
+## Step 1 – User Triggers the Action (Frontend)
+
+**UI Context**: Admin dashboard → User list → “Promote to SuperAdmin” button next to a user named “Alice”.
+
+**User clicks the button.**
+
+**Frontend behavior** (as per `high-risk-security-modal-hermes-flow.md`):
+
+- Immediately opens a prominent, non-dismissible `HighRiskSecurityModal`.
+- Modal displays:
+  - Clear warning: “This action will grant full system privileges to the selected user.”
+  - Required “Reason” textarea.
+  - Buttons: “Cancel” and “Request Manager Approval via Hermes”.
+
+**User enters the reason**:  
+“Alice needs SuperAdmin access to handle critical production incidents during the migration period. Security team has reviewed and approved.”
+
+User clicks “Request Manager Approval via Hermes”.
+
+---
+
+## Step 2 – Hermes Briefing to @manager
+
+**Frontend** constructs and sends a Hermes message to @manager:
+
+```json
+{
+  "type": "high_risk_approval_request",
+  "traceId": "TRACE-20260525-USER-PROMO-042",
+  "payload": {
+    "action": "PROMOTE_TO_SUPERADMIN",
+    "targetUserId": "user_0192",
+    "proposedBy": "admin_007",
+    "reason": "Alice needs SuperAdmin access to handle critical production incidents during the migration period. Security team has reviewed and approved."
+  }
+}
+```
+
+**@manager receives the briefing.**
+
+**@manager internal process** (as per corporate-governance knowledge):
+
+- Reads `high-risk-actions-managerapproval.md`
+- Reads `audit-logging-standard.md`
+- Assesses risk level (very high – SuperAdmin elevation)
+- Checks current project context and any existing policies
+
+**@manager response** (sent back via Hermes):
+
+```json
+{
+  "type": "high_risk_approval_response",
+  "traceId": "TRACE-20260525-USER-PROMO-042",
+  "status": "approved",
+  "managerApproval": {
+    "approvalId": "approval_88471",
+    "traceId": "TRACE-20260525-USER-PROMO-042",
+    "approvedBy": "manager",
+    "approvedAt": "2026-05-25T00:31:12Z",
+    "signature": "mgr-sig-20260525-88471",
+    "reason": "Approved for production incident handling during migration window. 30-day time-limited approval recommended."
+  }
+}
+```
+
+---
+
+## Step 3 – Frontend Receives Approval and Dispatches Request
+
+**Frontend**:
+- Receives the signed `managerApproval` token.
+- Closes the security modal.
+- Shows temporary status: “Manager approval received. Executing action…”
+- Attaches the token to the API request:
+
+```ts
+const payload = {
+  userId: "user_0192" as UserID,
+  newRole: "SuperAdmin",
+  isHighRiskAdminAction: true,
+  managerApproval: {
+    approvalId: "approval_88471",
+    traceId: "TRACE-20260525-USER-PROMO-042",
+    approvedBy: "manager",
+    approvedAt: "2026-05-25T00:31:12Z",
+    signature: "mgr-sig-20260525-88471",
+    reason: "Approved for production incident handling during migration window. 30-day time-limited approval recommended."
+  }
+};
+
+await fetch(`/api/v1/users/${userId}/role`, {
+  method: "POST",
+  body: JSON.stringify(payload)
+});
+```
+
+---
+
+## Step 4 – Backend Validation and Execution
+
+**@backend** receives the request.
+
+**Validation steps** (mandatory per `high-risk-actions-managerapproval.md` and `domain-error-handling-standard.md`):
+
+1. Checks `isHighRiskAdminAction === true`
+2. Validates presence and structure of `managerApproval`
+3. Verifies `managerApproval.approvedBy === "manager"`
+4. (In real system) Validates cryptographic signature or secure reference
+
+If any check fails → throws `HighRiskActionRequiresApprovalError`
+
+**Execution**:
+
+- Updates user role in database
+- Creates audit log entry (see `audit-logging-standard.md`):
+
+```ts
+await auditLogRepository.create({
+  traceId: "TRACE-20260525-USER-PROMO-042",
+  actorId: "admin_007" as UserID,
+  action: "USER_ROLE_ELEVATED_TO_SUPERADMIN",
+  targetId: "user_0192" as UserID,
+  beforeState: { role: "Admin" },
+  afterState: { role: "SuperAdmin" },
+  managerApprovalId: "approval_88471",
+  reason: "Approved for production incident handling during migration window..."
+});
+```
+
+- Returns success response with the used `approvalId`
+
+---
+
+## Step 5 – Frontend Feedback and Audit Visibility
+
+**Frontend**:
+- Shows success message: “Alice has been promoted to SuperAdmin. Action recorded with approval ID: approval_88471”
+- (Optional but recommended) Shows link to view the audit trail entry for this action
+
+**Audit log entry** is now queryable by authorized personnel (themselves subject to high-risk approval if they want to view full details).
+
+---
+
+## Key Governance Elements Demonstrated
+
+- User cannot bypass the security modal
+- Reason is mandatory and travels with the approval
+- @manager performs explicit risk assessment before issuing the token
+- Backend strictly validates the token before any state change
+- Full audit trail is created with reference to the approval
+- Trace ID connects the entire flow (UI → Hermes → Backend → Audit)
+
+This is the expected behavior for any high-risk action in a corporate project using Agent Enderun.
+
+**Anti-patterns shown as forbidden in this simulation**:
+- Frontend directly calling the API without the modal and approval
+- Backend executing the role change without validating `managerApproval`
+- Skipping audit logging for a privileged action
+- Re-using an old approval token without fresh @manager review

package/.enderun/knowledge/corporate-governance/high-risk-actions-managerapproval.md

@@ -0,0 +1,76 @@
+# High-Risk Administrative Actions & ManagerApproval Pattern
+
+**Applies to:** Any operation that changes user roles/permissions, system configuration, bulk data operations, or audit access.
+
+## Core Principle
+From ENDERUN.md Corporate CRUD Governance:
+> High-risk administrative operations are strictly under @manager control. Specialist agents must refuse and immediately redirect such requests to @manager.
+
+## Required Payload Shape
+Every high-risk request **must** include:
+
+```ts
+interface HighRiskActionPayload {
+  isHighRiskAdminAction: true;           // Explicit boolean flag
+  managerApproval: ManagerApproval;      // Cryptographically or procedurally signed token
+}
+
+interface ManagerApproval {
+  approvalId: ApprovalID;
+  traceId: TraceID;
+  approvedBy: 'manager';
+  approvedAt: string;                    // ISO-8601
+  signature: string;                     // In real systems: cryptographic signature or secure reference
+  reason: string;                        // Human-readable justification (mandatory)
+}
+```
+
+## Backend Enforcement Rules (@backend)
+1. If the action affects roles/permissions at Admin level or higher → treat as high-risk.
+2. Reject the request immediately (403) if either `isHighRiskAdminAction` or `managerApproval` is missing.
+3. Validate that `managerApproval.approvedBy === 'manager'`.
+4. Log the full approval token for audit.
+5. Never perform the state change before validation.
+
+## Frontend Requirements (@frontend)
+1. Any button or flow that can trigger a high-risk action must first open a **prominent, non-dismissible security modal**.
+2. The modal must:
+   - Clearly explain the risk and consequences.
+   - Require the user to enter a "reason".
+   - Only then initiate the Hermes briefing to @manager.
+3. The actual API call may only be made **after** a valid `managerApproval` token is returned from the briefing flow.
+
+## Hermes Coordination
+- @frontend → Hermes briefing to @manager with proposed action + reason.
+- @manager performs risk assessment and either:
+  - Issues a signed `managerApproval` token, or
+  - Rejects the request.
+- Only after receiving the token does the frontend dispatch the high-risk request to backend.
+
+## Concrete Payload Example (TypeScript)
+
+```ts
+// Request body for elevating a user to SuperAdmin
+interface PromoteToSuperAdminRequest {
+  userId: UserID;
+  newRole: 'SuperAdmin';
+  isHighRiskAdminAction: true;
+  managerApproval: {
+    approvalId: ApprovalID;
+    traceId: TraceID;
+    approvedBy: 'manager';
+    approvedAt: string;
+    signature: string;
+    reason: string;
+  };
+}
+```
+
+## Example High-Risk Actions (Non-Exhaustive)
+- Elevating any user to Admin or SuperAdmin
+- Resetting system-wide configuration
+- Bulk user deletion or data purge
+- Exporting full audit logs containing PII
+- Changing authentication providers or security policies
+
+This pattern is the foundation of trustworthy enterprise governance in Agent Enderun.

package/.enderun/knowledge/corporate-governance/high-risk-security-modal-hermes-flow.md

@@ -0,0 +1,49 @@
+# High-Risk Security Modal + Hermes Briefing Flow (Frontend Pattern)
+
+**Owner:** @frontend  
+**Related:** high-risk-actions-managerapproval.md
+
+## When to Use
+Any UI action that can result in a high-risk backend operation (see list in high-risk-actions document).
+
+## Required UI Behavior
+
+1. **Trigger Detection**
+   - The component must recognize that the intended action is high-risk (role elevation, bulk ops, etc.).
+
+2. **Security Modal (Mandatory)**
+   - Modal must be prominent (red/danger styling, large title "High-Risk Administrative Action").
+   - Must clearly state what is about to happen and the potential impact.
+   - Must contain a required free-text "Reason" field (this becomes part of the approval token).
+   - Must have clear "Cancel" and "Request Manager Approval" actions.
+   - Should not be dismissible by clicking outside while the request is in flight.
+
+3. **Hermes Briefing Flow**
+   - On "Request Manager Approval":
+     - Frontend sends a Hermes message to @manager containing:
+       - Proposed action
+       - Affected entities (e.g. userId)
+       - User-entered reason
+       - Current user context
+     - UI enters "Awaiting @manager approval" state (loading indicator + clear message).
+
+4. **Approval Reception**
+   - When @manager responds with a valid `managerApproval` token (via Hermes or secure channel), the frontend:
+     - Attaches the token to the request payload (`isHighRiskAdminAction: true`, `managerApproval`).
+     - Dispatches the actual API call.
+     - Shows success/failure feedback.
+
+5. **Audit & Traceability**
+   - The Trace ID from the approval must be visible or logged in the UI success state.
+   - The full approval reason must be recorded.
+
+## Anti-Patterns (Forbidden)
+- Performing the high-risk API call without the modal + reason.
+- Faking or locally generating the `managerApproval` object in the browser.
+- Hiding the risk from the user ("just click confirm").
+- Re-using old approval tokens.
+
+## Recommended Component Location
+`apps/web/src/components/ui/HighRiskSecurityModal.tsx` (or similar compound component).
+
+This pattern ensures that high-risk actions are never accidental and always carry a full audit trail through @manager.