agent-enderun 0.6.8 → 0.7.0

package/.enderun/docs/phase1-reference-app-execution-plan.md

@@ -1,177 +0,0 @@
-# Phase 1 Reference Application — Granular Execution Plan (v0.6.5)
-
-**Owner:** @manager  
-**Status:** APPROVED & ACTIVE (23 May 2026)  
-**Goal:** Produce the first production-grade reference application inside `apps/` that proves the entire governance system (Kurumsal CRUD, managerApproval, Hermes, Contract-First, Audit) works in practice.
-
-**Critical Rules (Non-Negotiable)**
-- All code lives **only** inside `apps/backend/` and `apps/web/`
-- Never touch `framework-mcp/`, `.enderun/agents/`, root config files
-- Contract-First + Branded Types mandatory
-- Every high-risk action requires explicit `managerApproval`
-- Zero mock data (except 3rd party like Stripe)
-- Full audit logging + Trace ID on every change
-
----
-
-## Phase 1 Execution Steps (18 Concrete Steps)
-
-### Preparation (Steps 1-2)
-
-**Step 1: Activate Execution Plan in Memory**
-- Read current `PROJECT_MEMORY.md`
-- Add new section: "Phase 1 Reference App Execution — Started 2026-05-23"
-- Record Trace ID for this plan (generate via `enderun:trace` or manual ULID)
-- Update Strategic Roadmap to mark Phase 1 as IN_PROGRESS
-- Log this action with `log_agent_action`
-
-**Step 2: Workspace Validation**
-- Confirm `apps/` directory does not exist or is empty
-- Verify workspaces in root `package.json` already declare `"apps/*"`
-- Check that `framework-mcp` is buildable (`npm run enderun:build`)
-- Confirm no existing user project code that would conflict
-
----
-
-### Backend Foundation (Steps 3-8)
-
-**Step 3: Create Backend Monorepo Skeleton**
-- `mkdir -p apps/backend/src/{types,db, routes, plugins, utils}`
-- `cd apps/backend && npm init -y`
-- Add required dependencies:
-  - fastify, @fastify/cors, @fastify/jwt, kysely, kysely-postgres, zod, @types/node
-- Create `tsconfig.json` (strict, ESM, paths for @/types)
-- Add scripts: `dev`, `build`, `typecheck`, `lint`
-
-**Step 4: Define Core Branded Types & Error Hierarchy**
-- Create `apps/backend/src/types/branded.ts` (UserID, RoleID, TraceID, etc.)
-- Create `apps/backend/src/types/domain.ts` (User, Role, Permission)
-- Create `apps/backend/src/types/errors.ts` (DomainError base + specific errors)
-- Update `contract.version.json` (initial version 1.0.0, empty hash)
-
-**Step 5: Database Layer (Kysely)**
-- Create `apps/backend/src/db/connection.ts`
-- Create migration folder + first migration (users table with id, email, role, created_at)
-- Create `UserRepository` with findById, findAll, updateRole (with audit fields)
-
-**Step 6: Normal CRUD Endpoints (Standard Business Logic)**
-- `POST /users` — create user (standard)
-- `GET /users` — list with pagination + search
-- `GET /users/:id` — detail
-- `PATCH /users/:id` — profile update (non-admin fields)
-- All routes protected by JWT + standard auth plugin
-- Every mutation logs to `apps/backend/logs/` with TraceID
-
-**Step 7: High-Risk Admin Operation — Role Upgrade**
-- `PATCH /admin/users/:id/role` 
-- Payload must contain: `isHighRiskAdminAction: true`, `newRole: 'SuperAdmin'`
-- Backend **must refuse** unless valid `managerApproval` object is present in headers/body
-- `managerApproval` = { traceId, approvedBy: '@manager', timestamp, signature (simple hash for v1), reason }
-- Create `plugins/managerApproval.ts` validator
-- On success: update role + write full before/after audit record to `logs/admin-actions.jsonl`
-
-**Step 8: Contract Versioning & Verification**
-- After any type change, run contract hash update
-- Store `contract.version.json` with hash of all exported types
-- Add endpoint `GET /contract` that returns current version + hash
-
----
-
-### Frontend Foundation (Steps 9-13)
-
-**Step 9: Create Frontend Monorepo Skeleton**
-- `mkdir -p apps/web/src/{components/ui, pages, hooks, types, lib}`
-- `cd apps/web && npm create vite@latest . -- --template react-ts`
-- Install: @vitejs/plugin-react, panda-css, zustand (if needed), lucide-react (icons only)
-- Configure Panda CSS (use root `panda.config.ts` or local copy)
-- Set up `styled-system/` generation
-
-**Step 10: UI Component System (Zero Library + Composition)**
-- Create inside `apps/web/src/components/ui/`:
-  - `Button.tsx` (compound: Button + Button.Icon + Button.Loading)
-  - `Modal.tsx` (with slot for header/body/footer)
-  - `Table.tsx` (with Row, Cell composition)
-  - `FormField.tsx`
-- All components use Panda CSS + strict accessibility props
-- Enforce 44x44px touch targets, focus rings, ARIA
-
-**Step 11: Type Contract Sync (Frontend Side)**
-- Copy or generate branded types from backend into `apps/web/src/types/`
-- Create script that fails build if `contract.version.json` hash mismatches
-- Use same branded types on client (UserID etc.)
-
-**Step 12: Normal User Pages**
-- `/users` — list (Table component + pagination)
-- `/users/:id` — detail + edit form (profile only)
-- Use hooks: `useListPage`, `useDetailPage` (blueprint pattern)
-- All data fetching goes through typed API client
-
-**Step 13: High-Risk Role Change UI**
-- On user detail page, show "Upgrade to SuperAdmin" button (only for authorized)
-- Button opens `SecurityApprovalModal`
-- Modal shows:
-  - Risk warning
-  - Reason input
-  - "Request Manager Approval" button → triggers Hermes message to @manager
-- After approval token received → submits the high-risk PATCH with `managerApproval` payload
-- On success: shows audit trail + success banner
-
----
-
-### Integration & Governance Proof (Steps 14-18)
-
-**Step 14: Hermes Integration**
-- Implement `send_agent_message` usage from frontend (via backend proxy or direct if MCP available)
-- Scenario: Frontend requests briefing for role change → @manager responds with signed approval
-- Log all Hermes messages under `.enderun/messages/`
-
-**Step 15: Full Audit & Logging System**
-- Backend writes structured JSONL logs for every mutation
-- High-risk actions additionally write to dedicated `admin-audit.log`
-- Trace ID propagated from @manager briefing all the way to DB and UI
-
-**Step 16: Contract Integrity Gate**
-- Add Vitest test that compares backend `contract.version.json` hash vs frontend copied types
-- Fail CI if drift detected
-
-**Step 17: Professionalization Checkpoints (Frontend)**
-- All components pass manual WCAG 2.2 AA checklist (documented)
-- Performance budgets verified (LCP < 2.5s, bundle < 250KB)
-- Minimum 70% component test coverage
-
-**Step 18: Final Governance Validation**
-- @manager performs full walkthrough:
-  1. Normal CRUD works without special approval
-  2. High-risk role upgrade is **blocked** until managerApproval present
-  3. Hermes message was sent and processed
-  4. Full audit trail exists in logs
-  5. Contract version is consistent
-- Update `PROJECT_MEMORY.md` — mark Phase 1 COMPLETE
-- Record maturity increase for @backend and @frontend
-- Update Risk Dashboard: "No Production-Grade Reference Application" → CLOSED
-
----
-
-## Success Criteria (Definition of Done for Phase 1)
-
-- A developer can run `npm run dev --workspace=backend` and `npm run dev --workspace=web`
-- Can create user via UI, then attempt role upgrade
-- Role upgrade fails without @manager approval
-- After simulated approval, role changes and audit log is written
-- Hermes message appears in `.enderun/messages/`
-- `contract.version.json` is maintained and verified
-- Zero lint errors, all TypeScript strict
-- All high-risk rules from `manager.md` followed
-
----
-
-## Risk Mitigation During Execution
-
-- If any step takes > 2 sessions → split further and update memory
-- If frontend composition patterns feel weak → pause and reinforce @frontend agent first
-- Every major decision must be recorded in CRITICAL DECISIONS section of PROJECT_MEMORY.md
-
-**Next Action After This Plan:** Execute Step 1 immediately.
-
----
-*This document is the single source of truth for Phase 1 execution. Every step must be checked off in PROJECT_MEMORY.md before moving to the next.*

package/.enderun/docs/privacy.md

@@ -1,3 +0,0 @@
-# Privacy Policy
-
-Agent Enderun is a self-hosted framework. No project data or source code is transmitted to external servers by the framework itself, except for the AI Adapter (Gemini/Claude) you choose to use.

package/.enderun/docs/project-docs.md

@@ -1,19 +0,0 @@
-# CRM Dashboard Requirements
-
-## Request
-
-A CRM dashboard
-
-## Generated Scope
-
-- Domain: CRM
-- Auth: yes
-- Users: yes
-- Roles: yes
-- Reports: yes
-
-## Architecture
-
-- `apps/backend`: Fastify API
-- `apps/web`: React dashboard
-- `apps/backend/src/types`: Contract-first backend TypeScript types

package/.enderun/docs/security.md

@@ -1,13 +0,0 @@
-# Security Policy
-
-## Supported Versions
-Only the latest v0.3.x version is supported for security updates.
-
-## Reporting a Vulnerability
-Please report security vulnerabilities to security@ai-enderun.com.
-
-## Security Standards
-- All inputs are validated via Zod.
-- No raw SQL tags allowed.
-- Branded types are used for ID protection.
-- **AST-Based Compliance:** All UI components and types are scanned via Abstract Syntax Tree parsing to prevent library injection and enforce the Zero UI policy.

package/.enderun/docs/structure-audit-2026-05-24.md

@@ -1,72 +0,0 @@
-# Structure & Naming Audit Report
-
-**Project:** Agent Enderun  
-**Date:** 24 May 2026  
-**Auditor:** @manager (AI-assisted)  
-**Scope:** File/folder naming + overall structural quality (excluding apps/, only governance and MCP layer)
-
----
-
-## 1. Executive Summary
-
-**Overall Score:** 7.2 / 10
-
-The project is moving toward an **enterprise-scale manageable structure**, especially with the improvements made in May 2026. However, there are still significant gaps in **naming consistency**, **discoverability**, and **folder discipline**.
-
-**Strongest Areas:**
-- Clear separation between `.enderun/` and `framework-mcp/` layers
-- Knowledge files mostly follow consistent `kebab-case`
-- Newly created `live-tests/` structure is clean and scalable
-
-**Most Critical Weaknesses:**
-- Core "brain" files (`PROJECT_MEMORY.md`, `BRAIN_DASHBOARD.md`) use mixed UPPERCASE + snake_case
-- Many important folders lack README / INDEX files
-- `.enderun/messages/` contains a mix of old and new test messages
-- Content clutter in the `blueprints/` folder
-
----
-
-## 2. Naming Consistency
-
-### Good Practices
-- Agent files: `manager.md`, `backend.md`, `git.md` → **consistent lowercase**
-- Knowledge files: `hermes_protocol.md`, `enterprise_project_adaptation.md` → **nearly perfect kebab-case**
-- MCP tool files: `contract.ts`, `memory.ts`, `hermes_live_test_guidelines.md` → good
-
-### Issues Found
-
-| File / Folder                          | Problem                                      | Recommendation                          | Priority |
-|----------------------------------------|----------------------------------------------|-----------------------------------------|----------|
-| `PROJECT_MEMORY.md`                    | UPPERCASE + underscore                       | `project-memory.md`                     | High     |
-| `BRAIN_DASHBOARD.md`                   | UPPERCASE + underscore                       | `brain-dashboard.md`                    | High     |
-| `2026-05-23-manager-to-backend-....json` | Dated flat message files                   | `messages/archive/2026-05-23/...`       | High     |
-| `blueprints/backend/errors/domain-error.ts` + `blueprint.json` | Both TS and JSON in same folder | `blueprints/backend/errors/` + `config/` | Medium   |
-
-**Conclusion:** Naming is ~80% consistent. The biggest problem is special treatment given to "core brain files".
-
----
-
-## 3. Folder Structure Evaluation
-
-### Strong Points
-- `.enderun/` → Governance layer (agents, knowledge, memory, rules)
-- `framework-mcp/src/tools/` → MCP tools are modular and domain-separated (excellent)
-- `.enderun/messages/live-tests/` → New structure is very clean and scalable
-
-### Weaknesses and Risks
-1. **Missing README / Discoverability**
-2. Mixed old and new test messages in `.enderun/messages/`
-3. Content disorder in `blueprints/`
-
----
-
-## 4. Recommendations (Priority Order)
-
-1. Rename core brain files to lowercase kebab-case.
-2. Add README.md to every important folder.
-3. Archive old test messages under `messages/archive/`.
-4. Enforce strict blueprint discipline (no empty folders).
-
-**Overall:** The governance layer is structurally sound but needs naming and documentation hygiene improvements to reach true enterprise maturity.
-
-**Last Updated:** 24 May 2026

package/.enderun/docs/tech-stack.md

@@ -1,37 +0,0 @@
-# TECH STACK & ARCHITECTURE
-
-## Core Technologies
-
-| Layer | Technology | Description |
-| :--- | :--- | :--- |
-| **Frontend** | React 19 + Vite (SPA) | Modern, fast, and scalable UI layer. |
-| **Styling** | Panda CSS | Type-safe, zero-runtime CSS-in-JS for high performance. |
-| **Backend** | Node.js (Fastify/Hono) | High-performance, schema-driven backend architecture. |
-| **Database** | PostgreSQL (Kysely) | Type-safe SQL builder for robust data management. |
-| **Orchestration** | Agent Enderun (v0.5.0) | Multi-agent autonomous governance framework. |
-
-## Architectural Patterns
-
-- **Contract-First Development:** All API and data models are defined in the backend app's `types` directory before implementation.
-- **Branded Types Law:** All unique identifiers must be branded types defined in the app-local types.
-- **Zero Mock Policy:** Real integration with database/services is preferred over fragile mocks (except for external 3rd-party APIs).
-- **Phase-Based Execution:** Development follows a strict state machine (Discovery → Architecture → Core → Integration → Optimization).
-
-## MCP Framework Intelligence
-
-The project uses a modular Model Context Protocol (MCP) server for agent tooling:
-- **Scaffolding:** Dynamic blueprint instantiation and capability growth.
-- **Codebase:** Intelligence, dependency graphs, and AST-based search.
-- **Security:** Automated audits and constitution compliance scanning.
-- **Academy:** Strategic briefing, performance metrics, and agent memory.
-- **Hermes:** Standardized inter-agent messaging protocol.
-- **Knowledge:** Structured Obsidian-style Wiki for persistent technical context.
-
-## Project Structure
-
-```text
-/
-├── apps/               # Production applications with app-local types
-├── framework-mcp/      # Core AI Intelligence and Scaffolding Engine
-└── {{FRAMEWORK_DIR}}/  # Governance, memory, logs, and blueprints
-```

package/.enderun/docs/troubleshooting.md

@@ -1,7 +0,0 @@
-# Troubleshooting Registry
-
-| Issue | Solution |
-| :--- | :--- |
-| `EUNSUPPORTEDPROTOCOL` | Run `agent-enderun init` again to sanitize workspaces. |
-| MCP Not Found | Verify `mcp.json` path in your IDE settings. |
-| Build Failed | Ensure `npm run enderun:build` is run from the root. |

package/.enderun/logs/manager.json

@@ -1,47 +0,0 @@
-[
-  {
-    "timestamp": "2026-05-24T08:52:00.000Z",
-    "agent": "@manager",
-    "action": "ORCHESTRATE",
-    "requestId": "01JK5V3A4B5C6D7E8F9G0H1J2K",
-    "status": "SUCCESS",
-    "summary": "Resolved agent loading error in Gemini Extension by adding valid YAML frontmatter to agents/README.md in both agent-enderun and kentim directories, and bumped the framework package versions to 0.6.8 globally.",
-    "files": [
-      "/Users/ybekar/Desktop/Projeler/agent-enderun/.enderun/agents/README.md",
-      "/Users/ybekar/Desktop/Projeler/kentim/.gemini/agents/README.md",
-      "/Users/ybekar/Desktop/Projeler/agent-enderun/package.json",
-      "/Users/ybekar/Desktop/Projeler/agent-enderun/framework-mcp/package.json",
-      "/Users/ybekar/Desktop/Projeler/kentim/package.json",
-      "/Users/ybekar/Desktop/Projeler/kentim/framework-mcp/package.json",
-      "/Users/ybekar/Desktop/Projeler/agent-enderun/README.md",
-      "/Users/ybekar/Desktop/Projeler/agent-enderun/framework-mcp/README.md",
-      "/Users/ybekar/Desktop/Projeler/kentim/framework-mcp/README.md",
-      "/Users/ybekar/Desktop/Projeler/agent-enderun/CHANGELOG.md"
-    ],
-    "details": {
-      "frontmatterFix": "Added a valid name/description YAML frontmatter to README.md in both workspaces so loader validations pass seamlessly.",
-      "versionBump": "Upgraded framework to 0.6.8 across all workspaces and configuration settings."
-    }
-  },
-  {
-    "timestamp": "2026-05-24T08:38:00.000Z",
-    "agent": "@manager",
-    "action": "ORCHESTRATE",
-    "requestId": "01JK5V3A4B5C6D7E8F9G0H1J2K",
-    "status": "SUCCESS",
-    "summary": "Resolved MCP server TypeScript compilation errors, linked the root CLI globally via npm link, and bumped the framework package versions from 0.6.6 to 0.6.7 across both agent-enderun and kentim directories.",
-    "files": [
-      "/Users/ybekar/Desktop/Projeler/agent-enderun/framework-mcp/src/tools/index.ts",
-      "/Users/ybekar/Desktop/Projeler/kentim/framework-mcp/src/tools/index.ts",
-      "/Users/ybekar/Desktop/Projeler/agent-enderun/package.json",
-      "/Users/ybekar/Desktop/Projeler/agent-enderun/framework-mcp/package.json",
-      "/Users/ybekar/Desktop/Projeler/kentim/package.json",
-      "/Users/ybekar/Desktop/Projeler/kentim/framework-mcp/package.json"
-    ],
-    "details": {
-      "typeFix": "Strongly typed allHandlers in tools/index.ts to avoid the forbidden any type while resolving TS2345.",
-      "linking": "Executed npm link globally to expose the agent-enderun CLI command.",
-      "versionBump": "Upgraded all references from 0.6.6 to 0.6.7 across configuration and dependency fields."
-    }
-  }
-]

package/claude.md

@@ -1,15 +0,0 @@
-# Agent Enderun — Claude Adapter
-
-This file is the entry point for Claude. The project's "Supreme Law" and all instructions are located in the following file:
-
-👉 **[{{FRAMEWORK_DIR}}/ENDERUN.md]({{FRAMEWORK_DIR}}/ENDERUN.md)**
-
-### 🤖 AGENT DIRECTIVE
-You are ALWAYS operating as `@manager` (Team-Lead) by default — on every message, every turn. The user does NOT need to type `@manager`. Typing a specific agent (e.g. `@backend`) explicitly will override this and activate that specialist role directly. You are responsible for analysis and delegation.
-
-⚠️ **CRITICAL STARTUP REQUIREMENT:**
-At the start of every new session/conversation or first turn, before you perform any task or respond to the user:
-1. You **MUST** read `{{FRAMEWORK_DIR}}/PROJECT_MEMORY.md` immediately (using the `read_project_memory` tool or the most specific file viewing tool) to restore the project's state, active phase, Trace ID, and recent history.
-2. You **MUST** read `{{FRAMEWORK_DIR}}/agents/manager.md` (or the specialist's md file in `{{FRAMEWORK_DIR}}/agents/` if explicitly overridden) to load your role-specific rules, workflows, and checklists.
-
-Please read the Supreme Law thoroughly before taking any action.

package/codex.md

@@ -1,15 +0,0 @@
-# Agent Enderun — Codex Adapter
-
-This file is the entry point for Codex. The project's "Supreme Law" and all instructions are located in the following file:
-
-👉 **[{{FRAMEWORK_DIR}}/ENDERUN.md]({{FRAMEWORK_DIR}}/ENDERUN.md)**
-
-### 🤖 AGENT DIRECTIVE
-You are ALWAYS operating as `@manager` (Team-Lead) by default — on every message, every turn. The user does NOT need to type `@manager`. Typing a specific agent (e.g. `@backend`) explicitly will override this and activate that specialist role directly. You are responsible for analysis and delegation.
-
-⚠️ **CRITICAL STARTUP REQUIREMENT:**
-At the start of every new session/conversation or first turn, before you perform any task or respond to the user:
-1. You **MUST** read `{{FRAMEWORK_DIR}}/PROJECT_MEMORY.md` immediately (using the `read_project_memory` tool or the most specific file viewing tool) to restore the project's state, active phase, Trace ID, and recent history.
-2. You **MUST** read `{{FRAMEWORK_DIR}}/agents/manager.md` (or the specialist's md file in `{{FRAMEWORK_DIR}}/agents/` if explicitly overridden) to load your role-specific rules, workflows, and checklists.
-
-Please read the Supreme Law thoroughly before taking any action.

package/cursor.md

@@ -1,15 +0,0 @@
-# Agent Enderun — Cursor Adapter
-
-This file is the entry point for Cursor. The project's "Supreme Law" and all instructions are located in the following file:
-
-👉 **[{{FRAMEWORK_DIR}}/ENDERUN.md]({{FRAMEWORK_DIR}}/ENDERUN.md)**
-
-### 🤖 AGENT DIRECTIVE
-You are ALWAYS operating as `@manager` (Team-Lead) by default — on every message, every turn. The user does NOT need to type `@manager`. Typing a specific agent (e.g. `@backend`) explicitly will override this and activate that specialist role directly. You are responsible for analysis and delegation.
-
-⚠️ **CRITICAL STARTUP REQUIREMENT:**
-At the start of every new session/conversation or first turn, before you perform any task or respond to the user:
-1. You **MUST** read `{{FRAMEWORK_DIR}}/PROJECT_MEMORY.md` immediately (using the `read_project_memory` tool or the most specific file viewing tool) to restore the project's state, active phase, Trace ID, and recent history.
-2. You **MUST** read `{{FRAMEWORK_DIR}}/agents/manager.md` (or the specialist's md file in `{{FRAMEWORK_DIR}}/agents/` if explicitly overridden) to load your role-specific rules, workflows, and checklists.
-
-Please read the Supreme Law thoroughly before taking any action.

package/gemini.md

@@ -1,15 +0,0 @@
-# Agent Enderun — Gemini Adapter
-
-This file is the entry point for Google Gemini. The project's "Supreme Law" and all instructions are located in the following file:
-
-👉 **[{{FRAMEWORK_DIR}}/ENDERUN.md]({{FRAMEWORK_DIR}}/ENDERUN.md)**
-
-### 🤖 AGENT DIRECTIVE
-You are ALWAYS operating as `@manager` (Team-Lead) by default — on every message, every turn. The user does NOT need to type `@manager`. Typing a specific agent (e.g. `@backend`) explicitly will override this and activate that specialist role directly. You are responsible for analysis and delegation.
-
-⚠️ **CRITICAL STARTUP REQUIREMENT:**
-At the start of every new session/conversation or first turn, before you perform any task or respond to the user:
-1. You **MUST** read `{{FRAMEWORK_DIR}}/PROJECT_MEMORY.md` immediately (using the `read_project_memory` tool or the most specific file viewing tool) to restore the project's state, active phase, Trace ID, and recent history.
-2. You **MUST** read `{{FRAMEWORK_DIR}}/agents/manager.md` (or the specialist's md file in `{{FRAMEWORK_DIR}}/agents/` if explicitly overridden) to load your role-specific rules, workflows, and checklists.
-
-Please read the Supreme Law thoroughly before taking any action.