agent-enderun 0.8.3 → 0.8.5

package/.enderun/PROJECT_MEMORY.md

@@ -39,6 +39,11 @@ This file is the Single Source of Truth (SSOT) and the persistent memory of the
 | Module | Status | Agent | Date |
 | :--- | :--- | :--- | :--- |
 
+## ACTIVE TASKS
+
+| Trace ID | Task | Agent | Priority | Status |
+| :--- | :--- | :--- | :--- | :--- |
+
 ## HISTORY (Persistent Memory)
 
 ### 2026-05-26 — Framework Cleanup

package/.enderun/STATUS.md

@@ -26,7 +26,7 @@
 
 | Metrik | Değer |
 | :--- | :--- |
-| **Framework Versiyonu** | v0.8.2 |
+| **Framework Versiyonu** | v0.8.5 |
 | **Sistem Sağlığı** | 🟢 GREEN |
 | **Toplam Trace** | 0 |
 | **Aktif Görevler** | 0 |

package/.enderun/claude.md

@@ -14,6 +14,6 @@ You are operating under the Agent Enderun governance framework.
 
 At the **start of every session**, before any work:
 1. Read `.claude/PROJECT_MEMORY.md` to restore state, active Trace ID, and history.
-2. Read the relevant agent definition under `.claude/agents/{agent}/agent.json` (especially `@manager`).
+2. Read the relevant agent definition under `.claude/agents/{agent}.md` (especially `@manager`).
 
 All paths and references inside `.claude/` use the Claude adapter structure. No migration to other CLIs is required.

package/.enderun/config.json

@@ -2,5 +2,5 @@
   "logLevel": "info",
   "outputFormat": "text",
   "defaultProfile": "Lightweight",
-  "version": "0.0.9"
+  "version": "0.8.5"
 }

package/.enderun/cursor.md

@@ -14,6 +14,6 @@ You are operating under the Agent Enderun governance framework.
 
 At the **start of every session**, before any work:
 1. Read `.cursor/PROJECT_MEMORY.md` to restore state, active Trace ID, and history.
-2. Read the relevant agent definition under `.cursor/agents/{agent}/agent.json` (especially `@manager`).
+2. Read the relevant agent definition under `.cursor/agents/{agent}.md` (especially `@manager`).
 
 All paths and references inside `.cursor/` use the Cursor adapter structure. No migration to other CLIs is required.

package/.enderun/knowledge/hermes_protocol.md

@@ -48,7 +48,7 @@ Every message sent via `send_agent_message` must follow this conceptual structur
 1.  **Dispatch:** Agent calls `send_agent_message`. Message is saved in `.enderun/messages/recipient.json`.
 2.  **Notification:** The recipient agent checks their inbox during their turn via `read_agent_messages`.
 3.  **Acknowledgment:** For `ACTION` or `DELEGATION`, the recipient should send an `INFO` message back once started or completed.
-4.  **Logging:** All critical communications must be summarized in the agent's log file (`.enderun/logs/agent.json`).
+4.  **Logging:** All critical communications must be summarized in the agent's specific log file (`.enderun/logs/{agent_name}.json`).
 
 ---
 

package/.enderun/memory-graph/shared-facts.json

@@ -47,6 +47,6 @@
     { "agent": "@native", "capability": 8.9, "primaryDomain": "native" },
     { "agent": "@mobile", "capability": 8.8, "primaryDomain": "mobile" }
   ],
-  "frameworkVersion": "0.8.2",
+  "frameworkVersion": "0.8.5",
   "constitutionFile": "ENDERUN.md"
 }

package/ENDERUN.md

@@ -1,4 +1,4 @@
-# Agent Enderun (v0.8.3)
+# Agent Enderun (v0.8.4)
 # Place in project root. This file is the single source of truth for Base Project AI Extensions.
 
 ## 🎖️ AGENT CHECKLIST (MANDATORY BEFORE RESPONSE)

package/README.md

@@ -1,9 +1,9 @@
-# 🏛️ Agent Enderun (v0.8.3) — The Supreme AI Governance & Orchestration Framework
+# 🏛️ Agent Enderun (v0.8.5) — The Supreme AI Governance & Orchestration Framework
 
 **The Supreme AI Governance & Orchestration Framework for Enterprise Development**
 
 **Author:** Yusuf BEKAR
-**Version:** 0.8.3
+**Version:** 0.8.5
 **License:** MIT
 
 [English](#english) | [Türkçe](#türkçe)
@@ -219,7 +219,7 @@ Enderun Ordusu'ndaki her ajan, kendilerine ait kuralları, izin verilen dizinler
 
 ---
 
-## 🏛️ Agent Enderun: Detaylı Kod Tabanı Denetim Raporu (v0.8.3)
+## 🏛️ Agent Enderun: Detaylı Kod Tabanı Denetim Raporu (v0.8.5)
 
 Çerçevenin (framework) çekirdek kod yapısı, operasyonel işleyişi, alt-üst ajan hiyerarşisi ve temizlenmiş mükerrer alanları en ince ayrıntısına kadar denetlenmiş ve belgelenmiştir:
 

package/claude.md

@@ -14,6 +14,6 @@ You are operating under the Agent Enderun governance framework.
 
 At the **start of every session**, before any work:
 1. Read `.claude/PROJECT_MEMORY.md` to restore state, active Trace ID, and history.
-2. Read the relevant agent definition under `.claude/agents/{agent}/agent.json` (especially `@manager`).
+2. Read the relevant agent definition under `.claude/agents/{agent}.md` (especially `@manager`).
 
 All paths and references inside `.claude/` use the Claude adapter structure. No migration to other CLIs is required.

package/cursor.md

@@ -14,6 +14,6 @@ You are operating under the Agent Enderun governance framework.
 
 At the **start of every session**, before any work:
 1. Read `.cursor/PROJECT_MEMORY.md` to restore state, active Trace ID, and history.
-2. Read the relevant agent definition under `.cursor/agents/{agent}/agent.json` (especially `@manager`).
+2. Read the relevant agent definition under `.cursor/agents/{agent}.md` (especially `@manager`).
 
 All paths and references inside `.cursor/` use the Cursor adapter structure. No migration to other CLIs is required.

package/docs/architecture/approval-flows.md

@@ -1,3 +1,61 @@
-# Enterprise Approval Flows Protocol
+# Enterprise Approval Flows & Governance Protocol (v0.8.5)
 
-This document defines the protocols for cross-agent approval flows in enterprise development.
+This protocol defines the strict governance model for high-risk operations and cross-agent approval flows within the Agent Enderun framework. It ensures that no critical mutations or sensitive actions are executed by AI specialists without formal orchestration and explicit authorization.
+
+---
+
+## 🔒 1. High-Risk Action Catalog
+
+Specialist agents (@backend, @frontend, @devops, etc.) are strictly prohibited from performing any of the following administrative operations autonomously. If requested, they must halt work, shift to `WAITING` status, and escalate to `@manager` via the **Hermes Protocol**.
+
+| Category | High-Risk Operations | Designated Controller |
+| :--- | :--- | :--- |
+| **Data Management** | Bulk delete/purge, data migration, PII export, schema modifications. | `@manager` |
+| **System Security** | Security credentials modification, CSP rule changes, private keys rotation. | `@security` & `@manager` |
+| **Infrastructure** | Production deployment triggers, container orchestration changes, ENV vars rotation. | `@devops` & `@manager` |
+| **Contract Stability**| Breaking API modifications, major type updates inside `src/types/`. | `@backend` & `@manager` |
+
+---
+
+## 💬 2. Hermes approval Flow (`managerApproval`)
+
+When a specialist agent encounters a high-risk operation, it must execute the following message queue protocol.
+
+### Step 1: Lock the Hermes Inbox
+To prevent race conditions, the agent must check for `{{FRAMEWORK_DIR}}/messages/.lock`. If the lock is active, the agent retries (up to 3 times, waiting 500ms between attempts). If no lock exists, it creates `.lock` to claim the channel.
+
+### Step 2: Write Approval Request File
+The requesting agent writes a structured JSON file inside `{{FRAMEWORK_DIR}}/queue/pending/` or `{{FRAMEWORK_DIR}}/messages/` with the unique `Trace ID` (ULID) and a `managerApproval` request flag:
+
+```json
+{
+  "traceId": "01JM5S8A0F2B4C6D8E0G2H4J6K",
+  "from": "@backend",
+  "to": "@manager",
+  "category": "ALERT",
+  "priority": "HIGH",
+  "action": "RUN_DATABASE_MIGRATION",
+  "payload": {
+    "migrationFile": "20260527_add_tenant_rls_policy.sql",
+    "rationale": "Enables multi-tenant Row Level Security (RLS) on PostgreSQL."
+  },
+  "timestamp": "2026-05-27T20:45:00Z"
+}
+```
+
+### Step 3: Shift Agent State
+The requesting agent updates its state inside `.enderun/STATUS.md` to `WAITING` and appends `BLOCKED_BY_APPROVAL` to its action log.
+
+### Step 4: Human-in-the-Loop Signing
+In production workspaces, the `@manager` compiles the war-room report and requests the human architect (CTO) to sign off on the transaction. The human developer signs the transaction by executing:
+```bash
+npx agent-enderun approve 01JM5S8A0F2B4C6D8E0G2H4J6K
+```
+Or by writing a signed token to the message queue.
+
+---
+
+## 🚦 3. Conflict Resolution & Rollback
+
+1.  **Approval Rejection:** If the transaction is rejected, `@manager` issues a `REJECTED` signal. The specialist agent rolls back any staged changes and returns to `IDLE` state.
+2.  **Stale Lock Recovery:** If a Hermes inbox `.lock` remains for more than 1.5 seconds, the active agent assumes a **stale lock** (LLM timeout), deletes the lock, and logs the incident to `@manager`.

package/docs/backend/error-handling.md

@@ -1,3 +1,74 @@
-# Professional Error Handling Pattern
+# Professional Domain Error Handling Pattern (v0.8.5)
 
-This document defines the standardized error handling patterns for backend services.
+All backend components developed under the Agent Enderun framework must comply with the **Domain Error Handling Protocol**. Direct usage of generic Javascript `Error` objects or HTTP status codes inside domain services is strictly forbidden.
+
+---
+
+## 🏛️ 1. DomainError Base Hierarchy
+
+We implement a strongly-typed, business-aware exception hierarchy. Every error thrown by the domain logic must inherit from the `DomainError` class.
+
+```typescript
+export abstract class DomainError extends Error {
+  public abstract readonly statusCode: number;
+  public abstract readonly errorCode: string;
+  public readonly timestamp: string;
+
+  constructor(message: string, public readonly metadata: Record<string, unknown> = {}) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = this.constructor.name;
+    this.timestamp = new Date().toISOString();
+  }
+}
+```
+
+### Core Exception Catalog
+
+*   **`NotFoundError` (HTTP 404):** Thrown when a resource (e.g., `User`, `Project`) identified by a **Branded Type ID** does not exist.
+*   **`ValidationError` (HTTP 400):** Thrown when data validation (usually Zod schemas) fails before processing business logic.
+*   **`ConflictError` (HTTP 409):** Thrown when database unique constraints or concurrent updates conflict.
+*   **`UnauthorizedError` (HTTP 401 / 403):** Thrown when RLS (Row Level Security) or RBAC policies are violated.
+
+---
+
+## ⚡ 2. Fastify Global Exception Handler
+
+Fastify must be configured with a single central error handler to map `DomainError` to client responses safely, preventing internal stack traces from leaking to the outside world.
+
+```typescript
+import { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+
+export function registerGlobalErrorHandler(server: FastifyInstance) {
+  server.setErrorHandler((error: Error, request: FastifyRequest, reply: FastifyReply) => {
+    if (error instanceof DomainError) {
+      server.log.warn({ err: error }, `Domain error: ${error.message}`);
+      return reply.status(error.statusCode).send({
+        success: false,
+        error: error.errorCode,
+        message: error.message,
+        timestamp: error.timestamp,
+        metadata: error.metadata
+      });
+    }
+
+    // Capture unhandled internal technical crashes
+    server.log.error({ err: error }, `Unhandled server crash: ${error.message}`);
+    return reply.status(500).send({
+      success: false,
+      error: "INTERNAL_SERVER_ERROR",
+      message: "An unexpected error occurred inside the system."
+    });
+  });
+}
+```
+
+---
+
+## 🔒 3. Branded Types & Query Constraints
+
+1.  **Branded Type Enforcement:** You must never accept raw string IDs inside repository query parameters. Always enforce compile-time type safety:
+    ```typescript
+    export type UserId = string & { readonly __brand: unique symbol };
+    ```
+2.  **Kysely Query Failures:** All Kysely queries running inside database transactions must be wrapped inside a `try/catch` block that translates SQL constraints into precise `ConflictError` or `UnauthorizedError` entities instead of throwing raw database query failures.

package/docs/frontend/component-patterns.md

@@ -1,3 +1,91 @@
-# Atomic Component Standards
+# Atomic Component Standards & Panda CSS Guidelines (v0.8.5)
 
-This document defines the atomic design principles and component standards for the frontend.
+All user interface developments inside the Agent Enderun framework must follow the **Fluid Component Protocol**. We strictly build component hierarchies following **Mobile-First Responsive Design** and type-safe styling using **Panda CSS**.
+
+---
+
+## 🚫 1. Absolute UI Policies
+
+### A. Zero UI Library Policy
+*   **The Law:** The use of external component libraries (e.g. TailwindCSS, Radix UI, Shadcn/ui, Material UI, Chakra UI, Ant Design) is strictly forbidden. 
+*   **The Reason:** This ensures absolute design authenticity, maximum bundle optimization, zero dependency bloat, and fully controlled accessibility (WCAG 2.2 AA).
+*   **Exception:** Low-level headless primitives (like `@radix-ui/react-dialog` for focus trapping or `sonner` for toast dispatchers) may be allowed, subject to direct approval by `@manager`.
+
+### B. Shared Component First Policy
+*   **The Law:** Defining reusable atomic components (Buttons, Inputs, Cards, Badges, Modals) inside page-level files is strictly forbidden.
+*   **The Structure:** All atomic items must be created inside `apps/web/src/components/ui/` as focused, single-purpose, highly modular components.
+
+---
+
+## 🐼 2. Panda CSS Styling Standards
+
+We utilize **Panda CSS** as our build-time type-safe CSS-in-JS engine. Raw inline styles or unmapped class names are completely banned.
+
+### A. Styling Token Best Practices
+Always leverage designated design tokens (colors, spacings, shadows) from the Panda config (`panda.config.ts`):
+
+```tsx
+import { css } from "../../styled-system/css";
+
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: "primary" | "secondary";
+}
+
+export function Button({ variant = "primary", className, children, ...props }: ButtonProps) {
+  return (
+    <button
+      className={css(
+        {
+          display: "inline-flex",
+          alignItems: "center",
+          justifyContent: "center",
+          px: "4",
+          py: "2.5",
+          borderRadius: "md",
+          fontSize: "sm",
+          fontWeight: "medium",
+          transition: "all 0.2s ease-in-out",
+          cursor: "pointer",
+          _disabled: { opacity: 0.5, cursor: "not-allowed" },
+        },
+        variant === "primary"
+          ? {
+              bg: "brand.primary",
+              color: "white",
+              _hover: { bg: "brand.primary.hover" },
+            }
+          : {
+              bg: "transparent",
+              color: "slate.700",
+              border: "1px solid",
+              borderColor: "slate.200",
+              _hover: { bg: "slate.50" },
+            }
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}
+```
+
+### B. Mobile-First Fluid Responsiveness
+Use array-based or object-based responsive syntax inside the `css` block. Never hardcode pixel values:
+
+```typescript
+// Enforce fluid flex layout across screen sizes
+const containerStyle = css({
+  display: "flex",
+  flexDirection: { base: "column", md: "row" }, // Mobile-first (column -> row on desktop)
+  gap: { base: "4", lg: "8" },
+  p: { base: "4", md: "6", xl: "8" }
+});
+```
+
+---
+
+## ♿ 3. Accessibility & QA Gates (WCAG 2.2)
+
+1.  **Aria Standards:** All custom interactive elements (dropdowns, mobile navigation draw-ins, accordion blocks) must support full keyboard navigation (Tab, Enter, Space) and have valid `aria-*` tags.
+2.  **Vitest Verification:** A component must never be merged into master without an accompanying test file (`[component].test.tsx`) that verifies the component renders correctly and responds to user click actions.

package/framework-mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-enderun-mcp",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "Enterprise-grade MCP Server for AI Agent Framework",
   "author": "Yusuf BEKAR",
   "license": "MIT",
@@ -36,10 +36,10 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "ts-morph": "^28.0.0",
-    "zod": "^4.4.3"
+    "zod": "^3.24.2"
   },
   "devDependencies": {
-    "@types/node": "^22.13.4",
+    "@types/node": "^25.9.1",
     "tsx": "^4.19.4",
     "typescript": "^5.9.3"
   }

package/framework-mcp/src/tools/framework.ts

@@ -118,10 +118,9 @@ export const frameworkHandlers = {
         if (!fs.existsSync(agentsDir)) {
             missing.push(`[MISSING FOLDER] ${frameworkDir}/agents`);
         } else {
-            const agents = fs.readdirSync(agentsDir).filter((f) => {
-                const fullAgentDir = path.join(agentsDir, f);
-                return fs.statSync(fullAgentDir).isDirectory() && fs.existsSync(path.join(fullAgentDir, "agent.json"));
-            });
+            const agents = fs.readdirSync(agentsDir)
+                .filter((f) => f.endsWith(".md") && f !== "README.md")
+                .map((f) => f.replace(".md", ""));
             const logsDir = path.join(projectRoot, frameworkDir, "logs");
             for (const agentName of agents) {
                 const logFile = path.join(logsDir, `${agentName}.json`);

package/framework-mcp/src/utils.ts

@@ -10,12 +10,12 @@ const getPackageVersion = (): string => {
         const pkgPath = path.join(__dirname, "../package.json");
         if (fs.existsSync(pkgPath)) {
             const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-            return pkg.version || "0.8.3";
+            return pkg.version || "0.8.5";
         }
     } catch {
         // fallback
     }
-    return "0.6.6";
+    return "0.8.5";
 };
 
 export const FRAMEWORK_VERSION = getPackageVersion();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-enderun",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "The Supreme AI Governance & Orchestration Framework for Enterprise Development",
   "author": "Yusuf BEKAR",
   "license": "MIT",

package/src/cli/index.ts

@@ -195,7 +195,7 @@ function mergePackageJson(targetPath: string, sourcePath: string): void {
     ...(sourceDevDeps["@types/node"] ? {"@types/node": sourceDevDeps["@types/node"]} : {}),
     ...(sourceDevDeps["tsx"] ? {"tsx": sourceDevDeps["tsx"]} : {}),
     ...(sourceDevDeps["vitest"] ? {"vitest": sourceDevDeps["vitest"]} : {}),
-    "@pandacss/dev": "^0.53.0"
+    "@pandacss/dev": sourceDevDeps["@pandacss/dev"] || "^1.11.1"
   });
 
   if ((targetPkg as PackageJson).peerDependencies) {