agent-enderun 1.1.2 → 1.1.4

package/.enderun/knowledge/corporate-governance/corporate-project-kickoff-simulation.md

@@ -1,144 +0,0 @@
-# Corporate Project Kickoff Simulation
-
-**Purpose**: This document provides a realistic, step-by-step simulation of how @manager should conduct the first sessions when a user starts a new corporate/enterprise project using Agent Enderun.
-
-**Scenario**: A company wants to build an internal "Enterprise User & Access Management" platform. The project will have normal CRUD operations plus high-risk administrative actions (role elevation, system configuration changes).
-
----
-
-## Session 1 – Initial Contact & Governance Baseline
-
-**User**:  
-"Hi, I need to build a user management system for our company. It should support roles like User, Admin, and SuperAdmin. Admins should be able to promote users, but promoting to SuperAdmin should be very controlled."
-
-**@manager (after loading all corporate-governance knowledge)**:
-
-Thank you. Before we discuss any features or technology, we need to establish the governance foundation for this project.
-
-This appears to be a corporate/enterprise project involving privileged operations. Therefore, we will follow Agent Enderun’s corporate standards from day one.
-
-The non-negotiable pillars are:
-
-1. **Branded Types** for all identifiers (see `branded-types-law.md`)
-2. **High-Risk Administrative Actions** protected by explicit `managerApproval` + Hermes coordination (see `high-risk-actions-managerapproval.md`)
-3. **Contract-first development** — types before implementation
-4. **Audit logging** for all privileged operations (see `audit-logging-standard.md`)
-5. **Typed Domain Errors** instead of generic exceptions (see `domain-error-handling-standard.md`)
-
-These standards exist to make the system safe, auditable, and maintainable at scale.
-
-I have prepared the **Corporate Project Kickoff Checklist**. We will go through the relevant parts together over the next sessions.
-
-Do you accept these operating rules for this project?
-
-**User**:  
-"Yes, that makes sense. We need proper controls especially around SuperAdmin promotions."
-
-**@manager**:
-Excellent. Acknowledgment recorded.
-
-We will now begin Phase 0 and Phase 1 of the Corporate Project Scaffolding SOP.
-
-First action: We will establish the type foundation before writing any feature code.
-
----
-
-## Session 2 – Contract & Type Foundation
-
-**@manager** (briefing to @backend and @frontend):
-
-Team,
-
-We are now in Phase 1 of the Corporate Project Scaffolding SOP.
-
-Required immediate deliverables:
-
-**@backend**:
-- Create `apps/backend/src/types/brand.ts`
-- Create `apps/backend/src/types/identifiers.ts` with `UserID`, `RoleID`, `ApprovalID`, `TraceID`
-- Create `apps/backend/src/types/approval.ts` with `ManagerApproval` and `HighRiskActionPayload`
-- Create `apps/backend/src/types/errors.ts` including `HighRiskActionRequiresApprovalError`
-- Initialize `apps/backend/contract.version.json`
-
-**@frontend**:
-- Create matching type copies in `apps/web/src/types/api-contracts.ts`
-- Begin designing the base `HighRiskSecurityModal` component structure (implementation will come in Phase 2)
-
-**@analyst**:
-- Establish contract integrity verification process
-
-No backend routes or frontend pages may be implemented until these contracts are defined and approved by me.
-
-Please confirm when the type foundation is ready for review.
-
----
-
-## Session 3 – High-Risk Governance Infrastructure
-
-**User**:  
-"We need to implement the 'Promote to SuperAdmin' feature soon."
-
-**@manager**:
-
-Understood. However, according to the Corporate Project Scaffolding SOP (Phase 2), we must build the high-risk governance infrastructure **before** implementing any privileged feature.
-
-This means:
-
-- @backend must implement strict validation that rejects any role elevation request unless `isHighRiskAdminAction: true` + valid `managerApproval` is present.
-- @frontend must build a prominent, non-dismissible Security Modal that forces the user to provide a reason before initiating the Hermes briefing to me (@manager).
-- Audit logging must be designed for every high-risk action (see `audit-logging-standard.md`).
-
-Only after these two layers exist will we proceed to implement the actual promotion feature.
-
-@backend and @frontend — I am now issuing the official briefing for Phase 2.
-
-Please reference:
-- `high-risk-actions-managerapproval.md`
-- `high-risk-security-modal-hermes-flow.md`
-- `domain-error-handling-standard.md`
-
-Confirm when the infrastructure design is ready for my approval.
-
----
-
-## Session 4 – Delegation Example (After Infrastructure Approval)
-
-**@manager** (to @backend):
-
-@backend,
-
-The high-risk infrastructure has been approved.
-
-You may now implement the following:
-
-**Feature**: `POST /api/v1/users/:id/role`
-
-Requirements:
-- Must use branded types only (`UserID`, `RoleID`, `ApprovalID`)
-- Must reject the request with `HighRiskActionRequiresApprovalError` if the high-risk payload is missing or invalid
-- Must create an audit log entry using the `AuditLog` domain (see `audit-logging-standard.md`)
-- Must follow the contract defined in `apps/backend/src/types/api-contracts.ts`
-
-Reference files:
-- `high-risk-actions-managerapproval.md`
-- `branded-types-law.md`
-- `domain-error-handling-standard.md`
-
-Do not proceed with any other privileged features until this endpoint is complete and reviewed.
-
----
-
-## Key Behaviors Demonstrated in This Simulation
-
-- @manager never allows feature work before governance foundation
-- @manager consistently references the knowledge files
-- @manager uses the Corporate Project Kickoff Checklist and Scaffolding SOP as the operating process
-- @manager educates the user while protecting the standards
-- All delegations are precise and reference the corporate governance documents
-
-This is the expected behavior for any corporate project.
-
----
-
-**Note for Agents**:  
-When conducting real sessions, adapt the language but never skip the governance steps. Shortcuts at the beginning create expensive problems later.

package/.enderun/knowledge/corporate-governance/corporate-project-scaffolding-sop.md

@@ -1,103 +0,0 @@
-# Corporate Enterprise Project Scaffolding SOP (for @manager)
-
-**Version:** 1.1  
-**Purpose**: This is the mandatory standard process that @manager must follow when a user initiates a new project with corporate, enterprise, or regulated characteristics.
-
-**Core Philosophy**:  
-Agent Enderun does **not** ship pre-built reference applications inside `apps/`.  
-Our value is in internalizing governance standards into the agents so that we can **guide the user** to build correctly, step by step, from the very first file.
-
----
-
-## Phase 0 – Discovery & Governance Baseline (Non-Negotiable First Step)
-
-Before any code is written or any feature is discussed in detail:
-
-1. **Load Corporate Governance Knowledge** (mandatory reads):
-   - `branded-types-law.md`
-   - `high-risk-actions-managerapproval.md`
-   - `high-risk-security-modal-hermes-flow.md`
-   - `audit-logging-standard.md`
-   - `governance-baseline-briefing-template.md`
-   - `audit-logging-standard.md` (when created)
-
-2. **Assess Project Context**:
-   - Does the project involve multiple users, roles, permissions, or privileged operations?
-   - Is there any requirement for audit trails, compliance, or high-risk administrative actions?
-   - Default assumption: Treat every new project as enterprise-grade unless the user explicitly states it is a simple internal prototype with no privileged actions.
-
-3. **Establish the Governance Contract** (before any technical discussion):
-   - Clearly communicate that the project will follow Agent Enderun corporate standards.
-   - Introduce the non-negotiable pillars:
-     - Branded Types for all domain identifiers
-     - High-risk actions protected exclusively by `managerApproval` + Hermes coordination
-     - Contract-first development (types before implementation)
-     - Comprehensive audit logging for privileged operations
-   - Obtain explicit user acknowledgment.
-
-4. **Document the Baseline Decision** in `docs/architecture/decisions/`.
-
-**Rule**: No feature work, no architecture discussion, and no delegation may begin until Phase 0 is complete and acknowledged.
-
----
-
-## Phase 1 – Foundation Layer (Contracts Before Any Implementation)
-
-1. **Create the Type System First** (`apps/backend/src/types`):
-   - `brand.ts` – Generic `Brand<T, Name>` utility
-   - `identifiers.ts` – `UserID`, `RoleID`, `ApprovalID`, `TraceID`, etc.
-   - `approval.ts` – `ManagerApproval` and `HighRiskActionPayload`
-   - `errors.ts` – DomainError base + concrete errors (including `HighRiskActionRequiresApprovalError`)
-   - `user.ts` / `role.ts` – Core domain entities
-   - `api-contracts.ts` – Initial request/response shapes for the first feature
-
-2. **Initialize Contract Versioning**:
-   - Create `apps/backend/contract.version.json` with proper MAJOR.MINOR version and hash.
-
-3. **Brief Supporting Agents**:
-   - Brief `@analyst` to establish contract integrity verification process.
-   - Brief `@frontend` to create parallel type copies and the base Security Modal component.
-
-**Strict Rule**: No backend route, no React component, and no database schema may be implemented until the relevant contracts are defined and approved by @manager.
-
----
-
-## Phase 2 – High-Risk Governance Infrastructure (Before Any Privileged Feature)
-
-If the project will contain user/role management, configuration changes, or any privileged operations:
-
-1. Design and document the complete `managerApproval` validation flow with `@backend`.
-2. Design and implement the Security Modal + Hermes briefing user flow with `@frontend`.
-3. Ensure both specialist agents have explicit instructions in their briefings referencing the corporate governance knowledge files.
-4. Verify that `@backend` will reject any high-risk request lacking the proper payload, and that `@frontend` will never bypass the modal.
-
-Only after these two infrastructure layers exist may actual feature development for privileged areas begin.
-
----
-
-## Phase 3 – Feature Development Under Strict Governance
-
-When delegating any work to `@backend` or `@frontend`:
-
-The briefing message **must** include:
-- Exact path to the contract types for this feature.
-- Classification of whether the feature contains high-risk actions.
-- Explicit references to the relevant files in `.enderun/knowledge/corporate-governance/`.
-- Requirement to notify @manager before implementing any high-risk path.
-- Mandate to produce ADR documentation for any new governance decisions.
-
-After delivery:
-- Require `@analyst` to perform contract alignment verification.
-- Require documentation of the implementation in the project’s decision records.
-
----
-
-## Phase 4 – Continuous Enforcement & Education
-
-- At the start of every session, re-read the corporate governance knowledge files.
-- Any proposal to “add governance later” or bypass standards must be treated as a process violation and rejected.
-- @manager is responsible for continuously educating the user and the specialist agents on the standards throughout the lifetime of the project.
-
----
-
-**This SOP is the primary mechanism by which Agent Enderun scales enterprise discipline without shipping example code.**

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

@@ -1,75 +0,0 @@
-# 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

@@ -1,211 +0,0 @@
-# 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

@@ -1,54 +0,0 @@
-# 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.