agent-enderun 0.6.0 → 0.6.5

package/README.md

@@ -1,7 +1,9 @@
-# 🏛️ Agent Enderun (v0.6.0) — The Supreme AI Governance Framework
+# 🏛️ Agent Enderun (v0.6.5) — The Supreme AI Governance Framework
 
 **The Supreme AI Governance & Orchestration Framework for Enterprise Development**
 
+**Geliştirici:** Yusuf BEKAR
+
 [English](#english) | [Türkçe](#türkçe)
 
 ---
@@ -10,758 +12,315 @@
 
 ## Executive Summary
 
-Agent Enderun, yazılım ekipleri için tasarlanmış, **Anayasal Yönetişim (Constitutional Governance)** ve **Çoklu Ajan Orkestrasyonu (Multi-Agent Orchestration)** sağlayan kurumsal düzeyde bir framework'tür. 
-
-### 🚀 v0.5.9: Adaptive Discovery & Token Economy Protocol
-
-- **Architecture Discovery Protocol (ADP):** Seamlessly ingest and adapt to existing (legacy) projects without rigid directory requirements.
-- **Token Economy & Context Management:** Advanced rules to optimize AI context usage, reducing token costs by up to 40%.
-- **Choice-Based Scaffolding:** Empowering users with consent-driven project setup and architectural blueprints.
-- **Modular MCP Ecosystem:** 30+ enterprise-grade intelligence tools for AST-based analysis and security.
-- **Zero Temporary Storage:** All task logs, plans, and state are strictly saved in persistent workspace directories; OS temp directories are completely forbidden.
-- **Session Memory Recovery:** Non-negotiable automatic first-turn state restoration and role initialization across all adapters.
+Agent Enderun is a **production-grade AI governance and multi-agent orchestration framework** designed for engineering teams that want to use AI assistants at scale without losing control, traceability, and professional discipline.
 
-### 🚀 v0.5.3: Zero-Config & Auto-Wiring
-- **Auto-Wiring:** CLI automatically configures `gemini-extension.json` for MCP.
-- **Automated Build:** Framework now compiles itself during initialization.
-- **Smart Directory Logic:** Enhanced separation between framework and project docs.
+While most AI coding tools focus on speed and generation, Agent Enderun focuses on **risk-aware, auditable, and continuously improving software development processes**. It transforms chaotic AI output into structured, enterprise-ready work through constitutional rules, specialized agents, and a living risk management system.
 
-### 🚀 v0.5.1: The Academy & Hermes Upgrade
+### Current Strategic Focus (May 2026)
 
-Bu sürümle birlikte Agent Enderun, basit bir yönetişim aracından otonom bir **Ajan Akademisi**'ne dönüşmüştür:
+The framework has entered a new phase: **Risk-Driven Agent Professionalization**.
 
-- **📡 Hermes Messaging Protocol:** Ajanlar arası kategorize edilmiş (Action/Delegation/Info) ve önceliklendirilmiş iletişim bus'ı.
-- **📚 Obsidian-Style LLM Wiki:** YAML metadata destekli, ilişkisel ve graf tabanlı teknik bilgi bankası yönetimi.
-- **🛡️ Contract-First Automation:** API ve tip kontratlarının SHA-256 ile otomatik doğrulanması.
-- **🤖 MCP Intelligence:** Bilgi grafiği üretme, inbox istatistikleri ve anlık sistem sağlığı denetimi sağlayan gelişmiş MCP araçları.
+Instead of only writing rules, we now actively track and close real risks through structured improvement programs for each agent. The current Risk Tracking Dashboard includes 6 critical risks, each with its own multi-week professionalization plan.
 
-Agent Enderun is a **production-grade AI governance framework** designed for engineering teams that must maintain control, traceability, and discipline when using AI assistants for code generation. It transforms chaotic AI output into structured, auditable, enterprise-ready deliverables through:
-
-- **Agent-Led Orchestration**: 8 specialized AI agent roles with defined responsibilities
-- **Contract-First Development**: Shared TypeScript types as the single source of truth
-- **Phase-Based Execution**: Strict workflow progression (PHASE_0 → PHASE_4)
-- **Enterprise Auditability**: Every decision, action, and commit is logged and traceable
-- **Modular MCP Intelligence**: 40+ tools across 12 categories for code analysis, security, and automation
+> **📋 Full Risk Tracking Dashboard**  
+> See the live status of all active risks: [docs/roadmap.md](docs/roadmap.md)
 
 ---
 
-## ⚡ 5-Minute Quick Start
-
-### Prerequisites
-- **Node.js**: 20+ (LTS recommended)
-- **npm**: 9+
-- **Git**: Initialized in your project root
-- **Any AI Adapter**: Gemini, Claude, Cursor, or Codex (optional but recommended)
-
-### Installation Steps
-
-#### Step 1: Clone or Initialize
-```bash
-# Option A: Clone this framework repository
-git clone https://github.com/ybekar/agent-enderun.git
-cd agent-enderun
-
-# Option B: Or use as npm package (when published)
-npx agent-enderun init gemini
-```
+## 🎯 Core Philosophy
 
-#### Step 2: Install Dependencies
-```bash
-npm install
-```
-
-#### Step 3: Build Framework
-```bash
-npm run enderun:build
-```
-
-#### Step 4: Verify Setup
-```bash
-agent-enderun check
-```
+Agent Enderun is built on four non-negotiable principles:
 
-Expected output:
-```
-✅ Framework active (v0.5.8)
-✅ MCP Server ready
-✅ Shared types compiled
-✅ Agent logs initialized
-✅ PROJECT_MEMORY.md found
-```
+1. **Single Point of Authority** — In enterprise projects, @manager is the only authorized entry point. No specialist agent may act without an official briefing.
+2. **Risk-First Mindset** — Every significant action is preceded by risk assessment, and high-risk operations require explicit approval and audit trails.
+3. **Continuous Agent Improvement** — All agents have maturity targets (minimum 8.0/10). We do not accept “good enough” in critical areas.
+4. **Zero Tolerance for Bypass** — Any attempt to circumvent governance (Hermes, briefings, memory updates, high-risk controls) is treated as a serious process violation.
 
 ---
 
-## 🤖 Adapter Automation Levels
+## 📊 Active Risk Tracking Dashboard (23 May 2026)
 
-Choose your AI adapter when running `init`. Each has a different automation level:
+We are currently managing the following 6 critical risks with dedicated improvement programs:
 
-| Adapter | Command | Automation | Notes |
-| :--- | :--- | :---: | :--- |
-| **Gemini** | `init gemini` | ✅ Full | MCP auto-wired into `gemini-extension.json`. One command, done. |
-| **Cursor** | `init cursor` | ✅ Full | `cursor.md` auto-synced to `.cursorrules`. One command, done. |
-| **Codex** | `init codex` | ✅ Full | Framework files placed in `.enderun/`. One command, done. |
-| **Claude** | `init claude` | ⚠️ Semi | After init, run one extra command shown in the terminal to register MCP tools. |
+| Risk                              | Current Status                          | Progress                          | Owner          |
+|-----------------------------------|-----------------------------------------|-----------------------------------|----------------|
+| Referans Uygulama Yokluğu         | No production-grade example exists      | Guidance documented               | @manager       |
+| @frontend Zayıflığı               | Component architecture & accessibility weak | 6-8 week Professionalization Program active | @manager |
+| Hermes “Kağıt Üzerinde”           | Protocol defined but not battle-tested  | Live Test Program (4 scenarios) defined | @manager |
+| Claude Otomasyonu                 | Semi-automatic, version inconsistencies | 60%                               | @manager       |
+| Gerçek Kullanım Eksikliği         | No long-term usage in real projects     | 0%                                | @manager       |
+| Kurumsal Yönetişim                | Strong on paper, proof still needed     | 85%                               | @manager       |
 
-> **Claude Note:** Claude Code requires explicit user approval for MCP tools due to its security model.
-> After `init claude`, copy and run the `claude config add ...` command shown in the terminal output.
+Each risk has a dedicated knowledge file and a clear improvement roadmap.
 
 ---
 
-## 🎯 What You Can Do Right Now
-
-### Initialize Your Project
-```bash
-# Creates {{FRAMEWORK_DIR}}/ directory with governance files
-npx agent-enderun init gemini
-```
+## 🤖 Agent Maturity Program (Target: All Agents ≥ 8.0)
 
-### Check Project Health
-```bash
-# Runs security audit, compliance check, and dependency analysis
-agent-enderun check
+We are running a structured professionalization program for all agents. Current maturity levels (May 2026):
 
-# Just security
-agent-enderun check:security
+| Agent              | Current | Target | Priority     | Status |
+|--------------------|---------|--------|--------------|--------|
+| **@manager**       | 8.0     | 9.5    | High         | Authority Audit system active |
+| **@backend**       | 7.5     | 9.0    | High         | Test culture & resilience needed |
+| **@frontend**      | 6.5     | 9.0    | **Critical** | 8-week Professionalization Program running |
+| **@analyst**       | 6.5     | 8.5    | Medium       | Governance audit capability improving |
+| **@explorer**      | 6.5     | 8.5    | Medium       | Risk area reporting being enforced |
+| **@git**           | 6.0     | 8.0    | Medium       | High-risk commit control added |
+| **@mobile**        | 2.0     | 8.0    | Low (future) | Major work required |
+| **@native**        | 2.0     | 8.0    | Low (future) | Major work required |
 
-# Just compliance
-agent-enderun check:compliance
-```
-
-### View Project Status
-```bash
-# Shows current phase, active agents, and blockers
-agent-enderun status
-```
-
-### Create a New Task
-```bash
-# Creates a ULID-based trace for a new feature
-agent-enderun trace:new "Implement User Authentication" backend P1
-```
-
-### Verify API Contracts
-```bash
-# Ensures shared-types and API docs are synchronized
-agent-enderun verify-contract
-```
+Full details and weekly plans are maintained in the Risk Tracking Dashboard.
 
 ---
 
-## 🏗️ Core Architecture
+## 🛡️ Key Governance Innovations (v0.6.5)
 
-Agent Enderun consists of **4 integrated layers**:
+### 1. Manager Authority Audit & Enforcement
+A formal system that requires @manager to regularly audit its own control over all agents and enforce violations through a defined escalation ladder.
 
-### Layer 1: Governance ({{FRAMEWORK_DIR}}/)
-```
-{{FRAMEWORK_DIR}}/
-├── ENDERUN.md              ← The "Supreme Law" (read this first!)
-├── PROJECT_MEMORY.md       ← Single source of truth for state
-├── STATUS.md               ← Agent status dashboard
-├── cli-commands.json       ← CLI ownership mapping
-├── agents/                 ← 8 agent role definitions
-├── logs/                   ← Audit trail (agent.json files)
-├── knowledge/              ← 16+ technical knowledge articles
-└── docs/api/               ← API contract specifications
-```
+### 2. Hermes Live Test Program
+A structured program with 4 mandatory real-world scenarios to move the Hermes protocol from “defined on paper” to “proven in practice”.
 
-### Layer 2: Framework Core (bin/ + packages/)
-```
-bin/cli.js                 ← CLI bootstrapper
-packages/
-├── framework-mcp/         ← 40+ MCP tools (12 categories)
-└── shared-types/          ← Branded types (single source of truth)
-```
-
-### Layer 3: Documentation (docs/)
-```
-docs/
-├── tech-stack.md          ← Approved technology stack
-├── project-docs.md        ← Product requirements (template)
-└── [your project files]   ← Your documents (agents will read these)
-```
+### 3. @frontend Professionalization Program
+An 8-week intensive program covering component architecture, accessibility (WCAG 2.2), performance, testing discipline, and high-risk admin + Hermes integration.
 
-### Layer 4: Application (apps/) — YOURS
-```
-apps/
-├── backend/               ← Your backend app (create this)
-├── web/                   ← Your frontend app (create this)
-└── [other apps]/          ← Mobile, desktop, etc.
-```
+### 4. Corporate CRUD & Administrative Governance
+All high-risk operations (user/permission management, bulk deletion, system configuration, audit access, etc.) now require explicit @manager briefing, `managerApproval` object, and full before/after audit logging.
 
 ---
 
-## 🎓 The Agent Academy — 8 Specialized Roles
+## 🏗️ Architecture Overview
 
-Each agent has a defined **Standard Operating Procedure (SOP)** and reads the constitution before every action.
+Agent Enderun is built on four layers:
 
-| Agent | Specialty | What They Do |
-|---|---|---|
-| **@manager** | Orchestration | Runs the phase machine, creates trace IDs, delegates tasks, updates PROJECT_MEMORY |
-| **@analyst** | Quality Control | Security audits, compliance checks, documentation debt, code review |
-| **@backend** | Data Architecture | Database schema, API contracts, shared-types integrity, Kysely standards |
-| **@frontend** | UI Development | React components, Panda CSS styling, Zero-UI Library enforcement, responsive design |
-| **@explorer** | Code Intelligence | Dependency graphs, complexity analysis, dead code detection, legacy code mapping |
-| **@git** | Repository Master | Semantic commits, branch management, conflict resolution, merge strategies |
-| **@mobile** | Mobile Apps | React Native, Expo, iOS/Android specifics, performance optimization |
-| **@native** | Native Apps | Tauri, Electron, native performance, IPC protocols, system integration |
+- **Governance Layer** (`{{FRAMEWORK_DIR}}/`) — Constitution, memory, agent definitions, knowledge base, logs
+- **Intelligence Layer** (`framework-mcp/`) — 40+ MCP tools for analysis, scaffolding, contract verification, and inter-agent communication
+- **CLI Layer** (`bin/`) — Project initialization and adapter automation
+- **Application Layer** (`apps/`) — Where the actual user applications live (currently empty — reference application is the next priority)
 
 ---
 
-## 🛠️ MCP Tools Reference
-
-The framework provides **40+ tools** organized in 12 categories. Agents use these automatically.
-
-### Framework Tools
-- `get_framework_status` — Check framework health
-- `get_project_gaps` — Identify missing files/structure
-- `get_memory_insights` — Analyze PROJECT_MEMORY
-- `bootstrap_legacy_memory` — Auto-detect existing projects
-
-### Codebase Tools
-- `search_codebase` — Find code patterns
-- `analyze_dependencies` — Map imports/exports
-- `analyze_codebase_intelligence` — Find complexity & dead code
-- `generate_dependency_graph` — Mermaid diagrams
-
-### Security & Compliance
-- `security_audit_scan` — Check for secrets, SQL injection, console.log
-- `analyze_constitution_compliance` — Enforce ENDERUN.md rules
-
-### Contract Management
-- `verify_api_contract` — Hash verification
-- `verify_contract_integrity` — Type synchronization
-- `update_contract_hash` — Sync shared-types
-
-### Git & Commits
-- `generate_semantic_commit_message` — Auto-generate commit messages
-
-### Academy Intelligence
-- `get_academy_performance` — Agent success rates
-- `generate_strategic_briefing` — High-level reports
-- `log_agent_action` — Structured logging
-
-### Repository Health
-- `validate_repository_health` — Run lint/test/build
-- `analyze_documentation_debt` — Find missing JSDoc/READMEs
-
-### Agent Collaboration
-- `send_agent_message` — Inter-agent communication
-- `read_agent_messages` — Check agent inbox
-
-### Database & Knowledge
-- `analyze_database_schema` — Extract ER diagrams
-- `search_knowledge_base` — Find technical guides
-- `update_knowledge_base` — Add knowledge entries
-
----
-
-## 📖 How Agents Read Your Project
-
-When you add documentation to `docs/`, agents automatically discover and use it:
-
-```
-docs/
-├── project-docs.md        ← Agents read here for requirements
-├── tech-stack.md          ← Technology decisions
-├── design-system.md       ← (optional) UI patterns
-├── api-guide.md           ← (optional) API examples
-└── architecture.md        ← (optional) System design
-```
-
-Agents use the `search_knowledge_base` tool to find answers to common questions.
-
----
-
-## ✅ Complete Installation Checklist
-
-- [ ] **Node.js 20+** installed (`node --version`)
-- [ ] **npm 9+** installed (`npm --version`)
-- [ ] **Git** initialized (`git init`)
-- [ ] **Framework installed** (`npm install && npm run enderun:build`)
-- [ ] **Health check passed** (`agent-enderun check` shows ✅)
-- [ ] **First task created** (`agent-enderun trace:new "Your task" backend P1`)
-- [ ] **Docs created** (add files to `docs/` for agents to read)
-- [ ] **MCP connected** (agents can now use tools)
-
----
-
-## 🚀 First Real Task
-
-Once everything is installed, try this:
+## ⚡ Quick Start
 
 ```bash
-# Step 1: Create a real project requirement
-echo "# User Authentication
+# 1. Initialize the framework (generates the .enderun/ structure)
+npx agent-enderun init
 
-Implement JWT-based authentication with refresh tokens.
-- Email/password login
-- Logout endpoint
-- Token refresh mechanism
-" > docs/requirements.md
+# 2. Install dependencies
+npm install
 
-# Step 2: Create a task
-agent-enderun trace:new "Implement Auth Module" backend P1
+# 3. Build the framework
+npm run enderun:build
 
-# Step 3: Agents read requirements and build
-# (They will automatically read docs/requirements.md)
+# 4. Verify setup
+npx agent-enderun check
 ```
 
----
+> **💡 Custom Adapter Option:** You can also initialize with a specific AI assistant/editor adapter if desired:  
+> `npx agent-enderun init [antigravity | claude | cursor | codex | gemini]`
 
-## 📁 Project Structure
-
-```
-agent-enderun/
-├── README.md                          ← This file
-├── package.json                       ← Root npm config
-├── bin/
-│   └── cli.js                         ← CLI entry point
-├── docs/                              ← Your project docs (agents read these)
-├── framework-mcp/                     ← MCP server (40+ tools)
-│   └── src/tools/
-│       ├── scaffold.ts                ← Blueprint construction
-│       ├── academy.ts
-│       ├── codebase.ts
-│       └── [10 more...]
-├── apps/                              ← Your applications (start here)
-│   ├── backend/
-│   │   ├── src/types/                 ← App-local contract types
-│   │   └── contract.version.json      ← SHA-256 integrity hash
-│   └── web/
-│       └── src/types/                 ← Frontend mirrors of backend types
-└── {{FRAMEWORK_DIR}}/                          ← Framework governance
-    ├── ENDERUN.md                     ← Constitution (MANDATORY READ)
-    ├── PROJECT_MEMORY.md              ← State machine
-    ├── STATUS.md                      ← Agent dashboard
-    ├── cli-commands.json              ← Command ownership
-    ├── config.json                    ← Configuration
-    ├── agents/                        ← 8 agent role docs
-    │   ├── manager.md
-    │   ├── analyst.md
-    │   ├── backend.md
-    │   ├── frontend.md
-    │   ├── explorer.md
-    │   ├── git.md
-    │   ├── mobile.md
-    │   └── native.md
-    ├── logs/                          ← Audit trail
-    │   ├── manager.json
-    │   ├── backend.json
-    │   ├── frontend.json
-    │   ├── analyst.json
-    │   ├── explorer.json
-    │   ├── git.json
-    │   ├── mobile.json
-    │   └── native.json
-    ├── knowledge/                     ← 16+ technical guides
-    │   ├── branded_types_pattern.md
-    │   ├── async_error_handling.md
-    │   ├── security_scanning.md
-    │   ├── contract_versioning.md
-    │   ├── git_commit_strategy.md
-    │   ├── testing_standards.md
-    │   └── [12 more...]
-    ├── messages/                      ← Inter-agent communication
-    └── docs/
-        ├── api/                       ← API contracts
-        │   ├── auth.md
-        │   ├── errors.md
-        │   └── README.md
-        └── [other docs]
-```
+For a complete step-by-step guide, see: [docs/getting-started.md](docs/getting-started.md)
 
 ---
 
-## 💡 Frequently Asked Questions
-
-### Q: What does "contract-first" mean?
-**A:** All API shapes and domain models are defined in `packages/shared-types/src/index.ts` **before** any code is written. Frontend and backend must both use these types, ensuring perfect alignment.
-
-### Q: Do agents actually understand all this?
-**A:** Yes. Before every action, agents read:
-1. `ENDERUN.md` (the constitution)
-2. `{{FRAMEWORK_DIR}}/PROJECT_MEMORY.md` (project state)
-3. `docs/` files (your requirements)
-4. `{{FRAMEWORK_DIR}}/knowledge/` (technical guidelines)
-
-### Q: What if I don't use an AI adapter?
-**A:** The framework still works as a **collaborative development platform**. You and your team use it to enforce:
-- Phase progression
-- Audit logging
-- Shared type discipline
-- API contract verification
+## 🧠 Current Honest Status (23 May 2026)
 
-### Q: Can I extend the MCP tools?
-**A:** Yes. Add new tool files in `packages/framework-mcp/src/tools/`, define the schema, and export the handler. The CLI will automatically discover them.
+**Strong Areas:**
+- Constitutional governance and mandatory rules
+- Risk management and agent professionalization system
+- Inter-agent communication protocol (Hermes) technical foundation
+- Backend patterns and contract-first discipline
+- Memory discipline and audit logging
 
-### Q: How do I add my own agents?
-**A:** Create a markdown file in `{{FRAMEWORK_DIR}}/agents/your-agent.md`, define the SOP, and add a CLI mapping in `{{FRAMEWORK_DIR}}/cli-commands.json`.
-
-### Q: Is this production-ready?
-**A:** The **framework** is production-ready. Individual features (like `apps/`) depend on what you build. Start with `apps/backend` or `apps/web`.
+**Areas Still Maturing:**
+- No complete reference application yet (highest priority)
+- @frontend still below target maturity
+- Hermes has not been fully stress-tested in real multi-agent scenarios
+- Real long-term usage data is limited
+- Mobile and Native agents are still early stage
 
 ---
 
-## 🔗 Key Files to Read First
+## 📍 Next Major Milestones
 
-1. **`{{FRAMEWORK_DIR}}/ENDERUN.md`** — The constitution (rules all agents must follow)
-2. **`{{FRAMEWORK_DIR}}/PROJECT_MEMORY.md`** — Current project state and history
-3. **`docs/tech-stack.md`** — Technology decisions
-4. **`packages/shared-types/src/index.ts`** — The contract (types)
-5. **`README.md`** (this file) — How to use the framework
+1. Build a real reference application demonstrating Normal CRUD + High-Risk Admin + Hermes usage
+2. Complete @frontend Professionalization Program (target: 9.0)
+3. Execute and close Hermes Live Test Program
+4. Raise all agents to minimum 8.0 maturity
 
 ---
 
-## 📞 Support & Contribution
+## 📚 Further Reading
 
-### Report Issues
-File issues with clear reproduction steps and framework version.
+- **[docs/roadmap.md](docs/roadmap.md)** — Full Risk Tracking Dashboard and development roadmap
+- **[docs/strategic-review-2026-05.md](docs/strategic-review-2026-05.md)** — Independent strategic assessment
+- **.enderun/agents/** — Detailed Standard Operating Procedures for all 8 agents
+- **.enderun/knowledge/** — Specialized technical and governance guides
 
-### Contribute
-1. Read `{{FRAMEWORK_DIR}}/ENDERUN.md`
-2. Follow the agent role guidelines
-3. Submit PRs with semantic commit messages
-4. Ensure tests pass: `npm run enderun:build`
+---
 
-### License
-MIT © 2026 Yusuf BEKAR
+**Agent Enderun is not just a tool. It is a complete operating system for professional AI-assisted software development.**
 
 ---
 
 # Türkçe
 
-## Genel Özet
+**Geliştirici:** Yusuf BEKAR
 
-Agent Enderun, **kurumsal-grade bir yapay zeka yönetim çerçevesidir** ve yapay zeka asistanlarını kontrol altında tutmanız, izlenebilir olmasını sağlamanız ve disiplinli kod üretimini garantilamanız için tasarlanmıştır.
+## Yönetici Özeti
 
-- **Ajan Orkestrasyonu**: 8 uzmanlaşmış yapay zeka rolü
-- **Sözleşme-İlk Geliştirme**: Paylaşılan TypeScript türleri
-- **Faz Tabanlı Yürütme**: Sıkı iş akışı (PHASE_0 → PHASE_4)
-- **Kurumsal Denetim**: Her karar, işlem ve commit kaydedilir
-- **Modüler MCP Zekası**: 40+ araç, 12 kategori
+Agent Enderun, yazılım ekipleri için tasarlanmış **Anayasal Yönetişim (Constitutional Governance)** ve **Çoklu Ajan Orkestrasyonu** odaklı kurumsal düzeyde bir yapay zeka yönetim ve orkestrasyon framework’üdür.
 
----
+Çoğu AI kod aracı hız ve üretim kapasitesine odaklanırken, Agent Enderun **risk bilinci, denetlenebilirlik, izlenebilirlik ve sürekli profesyonel gelişim** üzerine kuruludur. Kaotik ve kontrolsüz AI çıktılarını yapılandırılmış, kurumsal standartlara uygun, denetlenebilir ve hesap verebilir işlere dönüştürür.
 
-## ⚡ 5 Dakikalık Hızlı Başlangıç
+### Mayıs 2026 İtibarıyla Stratejik Odak
 
-### Gereksinimler
-- **Node.js**: 20+ (LTS önerilir)
-- **npm**: 9+
-- **Git**: Proje kökünde başlatılmış
-- **AI Adaptörü** (opsiyonel): Gemini, Claude, Cursor veya Codex
+Framework, yeni ve daha olgun bir döneme girmiş durumdadır: **Risk Odaklı Ajan Profesyonelleşmesi**.
 
-### Kurulum Adımları
+Artık sadece kural yazmakla yetinilmiyor. Her ajanın gerçek hayattaki riskleri takip ediliyor ve bu riskleri kapatmak için yapılandırılmış, çok haftalık iyileştirme programları yürütülüyor. Şu anda 6 kritik risk aktif olarak takip ediliyor ve her biri için özel profesyonelleşme planları bulunuyor.
 
-#### Adım 1: Clone veya İnit
-```bash
-# Seçenek A: Framework repository'sini klonla
-git clone https://github.com/ybekar/agent-enderun.git
-cd agent-enderun
+> **📋 Risk Takip Panosu**  
+> Tüm aktif risklerin güncel durumunu görmek için: [docs/roadmap.md](docs/roadmap.md)
 
-# Seçenek B: veya npm paketi olarak kullan
-npx agent-enderun init gemini
-```
+---
 
-#### Adım 2: Bağımlılıkları Yükle
-```bash
-npm install
-```
+## 🎯 Temel Felsefe
 
-#### Adım 3: Framework'ü Derle
-```bash
-npm run enderun:build
-```
+Agent Enderun dört vazgeçilmez ilke üzerine inşa edilmiştir:
 
-#### Adım 4: Kurulumu Doğrula
-```bash
-agent-enderun check
-```
-
-Beklenen çıktı:
-```
-✅ Framework aktif (v0.5.8)
-✅ MCP Sunucu hazır
-✅ Paylaşılan türler derlenmiş
-✅ Agent logları başlatılmış
-✅ PROJECT_MEMORY.md bulundu
-```
+1. **Tek Yetki Noktası** — Kurumsal projelerde @manager tek yetkili giriş noktasıdır. Hiçbir uzman ajan, resmi ve yapılandırılmış bir briefing almadan kullanıcıya cevap veremez veya iş yapamaz.
+2. **Risk Öncelikli Yaklaşım** — Her önemli işlem öncesi risk değerlendirmesi yapılır. Yüksek riskli işlemler için açık @manager onayı ve detaylı audit kaydı zorunludur.
+3. **Sürekli Ajan Geliştirme** — Tüm ajanların olgunluk hedefi minimum **8.0/10** olarak belirlenmiştir. Kritik alanlarda “yeterince iyi” kabul edilmez.
+4. **Sıfır Tolerans** — Yönetişimi bypass eden her girişim (Hermes kullanımı, briefing zorunluluğu, memory güncelleme, yüksek riskli işlem kontrolleri) ciddi süreç ihlali olarak değerlendirilir ve kayıt altına alınır.
 
 ---
 
-## 🎯 Şu Anda Yapabileceğiniz İşler
-
-### Projeyi Başlat
-```bash
-npx agent-enderun init gemini
-```
-
-### Sağlık Durumunu Kontrol Et
-```bash
-agent-enderun check                 # Tam kontrol
-agent-enderun check:security        # Sadece güvenlik
-agent-enderun check:compliance      # Sadece uyum
-```
+## 📊 Aktif Risk Takip Panosu (23 Mayıs 2026)
 
-### Proje Durumunu Görüntüle
-```bash
-agent-enderun status
-```
+Şu anda aşağıdaki 6 kritik risk, özel iyileştirme programlarıyla aktif olarak yönetilmektedir:
 
-### Yeni Görev Oluştur
-```bash
-agent-enderun trace:new "Kullanıcı Doğrulama Uygulaması" backend P1
-```
+| Risk                              | Mevcut Durum                                      | İlerleme Durumu                                      | Sahip      |
+|-----------------------------------|---------------------------------------------------|------------------------------------------------------|------------|
+| Referans Uygulama Yokluğu         | Henüz production-grade bir örnek proje yok        | Rehber ve program tanımlandı                         | @manager   |
+| @frontend Zayıflığı               | Bileşen mimarisi ve erişilebilirlik zayıf         | 6-8 haftalık Profesyonelleşme Programı aktif         | @manager   |
+| Hermes “Kağıt Üzerinde”           | Protokol tanımlı ancak gerçek hayatta test edilmedi | 4 senaryoluk Canlı Test Programı tanımlandı          | @manager   |
+| Claude Otomasyonu                 | Yarı otomatik, farklı versiyonlarda sorunlar var  | %60                                                  | @manager   |
+| Gerçek Kullanım Eksikliği         | Gerçek projelerde uzun süreli kullanım verisi yok | %0                                                   | @manager   |
+| Kurumsal Yönetişim                | Kurallar kağıt üzerinde güçlü, kanıt henüz yetersiz | %85                                                  | @manager   |
 
-### API Kontratlarını Doğrula
-```bash
-agent-enderun verify-contract
-```
+Her risk için ayrı bir knowledge dosyası ve net bir iyileştirme yol haritası bulunmaktadır.
 
 ---
 
-## 🤖 Adaptör Otomasyon Seviyeleri
+## 🤖 Ajan Olgunluk Programı (Hedef: Tüm Ajanlar ≥ 8.0)
 
-`init` komutunu çalıştırırken adaptörünüzü seçin. Her adaptörün otomasyon seviyesi farklıdır:
+Tüm ajanlar için yapılandırılmış bir profesyonelleşme programı yürütülmektedir. Mayıs 2026 itibarıyla mevcut olgunluk seviyeleri şu şekildedir:
 
-| Adaptör | Komut | Otomasyon | Not |
-| :--- | :--- | :---: | :--- |
-| **Gemini** | `init gemini` | ✅ Tam | MCP `gemini-extension.json`'a otomatik yazılır. Tek komut, bitti. |
-| **Cursor** | `init cursor` | ✅ Tam | `cursor.md` otomatik olarak `.cursorrules`'a kopyalanır. Tek komut, bitti. |
-| **Codex** | `init codex` | ✅ Tam | Framework dosyaları `.enderun/` dizinine yerleştirilir. Tek komut, bitti. |
-| **Claude** | `init claude` | ⚠️ Yarı | Init sonrası terminalde gösterilen `claude config add ...` komutunu çalıştırmanız gerekir. |
+| Ajan               | Mevcut | Hedef | Öncelik     | Durum |
+|--------------------|--------|-------|-------------|-------|
+| **@manager**       | 8.0    | 9.5   | Yüksek      | Authority Audit & Enforcement sistemi aktif |
+| **@backend**       | 7.5    | 9.0   | Yüksek      | Test kültürü ve resilience güçlendiriliyor |
+| **@frontend**      | 6.5    | 9.0   | **Kritik**  | 8 haftalık Profesyonelleşme Programı devam ediyor |
+| **@analyst**       | 6.5    | 8.5   | Orta        | Governance denetim ve metrik yeteneği geliştiriliyor |
+| **@explorer**      | 6.5    | 8.5   | Orta        | Riskli alan raporlaması zorunlu hale getiriliyor |
+| **@git**           | 6.0    | 8.0   | Orta        | Yüksek riskli commit kontrolü eklendi |
+| **@mobile**        | 2.0    | 8.0   | Düşük       | İleride büyük çalışma gerekecek |
+| **@native**        | 2.0    | 8.0   | Düşük       | İleride büyük çalışma gerekecek |
 
-> **Claude Notu:** Claude Code, güvenlik modeli gereği MCP araçlarının kullanıcı tarafından açıkça onaylanmasını zorunlu kılar.
-> `init claude` sonrası terminal çıktısındaki `claude config add ...` komutunu kopyalayıp çalıştırın.
+Detaylı haftalık planlar ve gelişim raporları Risk Takip Panosu’nda yer almaktadır.
 
 ---
 
-## 🏗️ Temel Mimari
-
-Agent Enderun **4 entegre katmandan** oluşur:
+## 🛡️ Önemli Yönetişim Yenilikleri (v0.6.5)
 
-### Katman 1: Yönetişim ({{FRAMEWORK_DIR}}/)
-- `ENDERUN.md` — Anayasa (bunu ilk oku!)
-- `PROJECT_MEMORY.md` — Proje durumu
-- `agents/` — 8 ajan rolü tanımları
-- `logs/` — Denetim kaydı
-- `knowledge/` — 16+ teknik rehberi
-- `docs/api/` — API sözleşmeleri
+### 1. Manager Authority Audit & Enforcement
+@manager’ın tüm ajanlar üzerindeki kontrolünü düzenli olarak denetlemesini ve ihlalleri tanımlanmış bir süreçle (düzeltme → kayıt → koçluk → kapsam kısıtlama) düzeltmesini sağlayan resmi sistem.
 
-### Katman 2: Framework Çekirdeği
-- `packages/framework-mcp/` — 40+ MCP aracı
-- `packages/shared-types/` — Paylaşılan türler (sözleşme)
-- `bin/cli.js` — CLI başlatıcısı
+### 2. Hermes Live Test Programı
+Hermes protokolünün “kağıt üzerinde tanımlı” olmaktan çıkıp “gerçek hayatta kanıtlanmış” hale gelmesi için 4 zorunlu canlı senaryo (Delegasyon, Yüksek Riskli İşlem Koordinasyonu, Çatışma Çözümü, Bilgi Paylaşımı) içeren yapılandırılmış program.
 
-### Katman 3: Dokümantasyon
-- `docs/tech-stack.md` — Teknoloji kararları
-- `docs/project-docs.md` — Ürün gereksinimleri
-- Ajanlar bu dosyaları okurlar
+### 3. @frontend Profesyonelleşme Programı
+Bileşen mimarisi (Compound Components & Slots), erişilebilirlik (WCAG 2.2 AA), performans mühendisliği, test disiplini ve yüksek riskli admin işlemleri + Hermes entegrasyonunu kapsayan 8 haftalık yoğun program.
 
-### Katman 4: Uygulamalarınız
-- `apps/backend/` — Backend uygulaması (siz oluşturun)
-- `apps/web/` — Frontend uyguması (siz oluşturun)
+### 4. Kurumsal CRUD ve Yönetimsel İşlem Yönetişimi
+Kullanıcı/yetki yönetimi, toplu silme, sistem konfigürasyonu, audit log erişimi gibi yüksek riskli işlemler artık zorunlu @manager briefing, `managerApproval` nesnesi ve detaylı before/after audit log ile yapılmak zorundadır.
 
 ---
 
-## 🎓 Ajan Akademisi — 8 Uzman Rol
-
-| Ajan | Uzmanlık | Görev |
-|---|---|---|
-| **@manager** | Orkestrasyoun | Faz yönetimi, trace ID, görev delegasyonu |
-| **@analyst** | Kalite Kontrol | Güvenlik denetimi, uyum kontrolü, kod incelemesi |
-| **@backend** | Veri Mimarisi | Veritabanı, API kontratları, Kysely standartları |
-| **@frontend** | UI Geliştirme | React, Panda CSS, bileşen tasarımı |
-| **@explorer** | Kod Zekası | Bağımlılıklar, karmaşıklık, ölü kod |
-| **@git** | Repository Ustası | Semantik commit'ler, branch yönetimi |
-| **@mobile** | Mobil Uygulamalar | React Native, Expo, iOS/Android |
-| **@native** | Yerel Uygulamalar | Tauri, Electron, sistem entegrasyonu |
-
----
+## 🏗️ Mimari Özet
 
-## ✅ Komple Kurulum Kontrol Listesi
+Agent Enderun dört ana katmandan oluşur:
 
-- [ ] **Node.js 20+** yüklü (`node --version`)
-- [ ] **npm 9+** yüklü (`npm --version`)
-- [ ] **Git** başlatılmış (`git init`)
-- [ ] **Framework yüklü** (`npm install && npm run enderun:build`)
-- [ ] **Sağlık kontrolü geçti** (`agent-enderun check` ✅ gösteriyor)
-- [ ] **İlk görev oluşturuldu** (`agent-enderun trace:new "Görev" backend P1`)
-- [ ] **Doklar oluşturuldu** (`docs/` klasörüne dosya ekledim)
-- [ ] **MCP bağlandı** (ajanlar araçları kullanabiliyor)
+- **Yönetişim Katmanı** (`{{FRAMEWORK_DIR}}/`) — Anayasa (`ENDERUN.md`), bellek (`PROJECT_MEMORY.md`), ajan tanımları, bilgi tabanı, loglar
+- **Zeka Katmanı** (`framework-mcp/`) — 40+ MCP aracı (kod analizi, scaffolding, kontrat doğrulama, ajan iletişimi, güvenlik taraması vb.)
+- **CLI Katmanı** (`bin/`) — Proje başlatma ve adaptör otomasyonu
+- **Uygulama Katmanı** (`apps/`) — Gerçek kullanıcı uygulamalarının geliştirileceği alan (şu anda boş — referans uygulama en yüksek önceliktir)
 
 ---
 
-## 🚀 İlk Gerçek Görev
-
-Kurulum tamamlandıktan sonra bunu deneyin:
+## ⚡ Hızlı Başlangıç
 
 ```bash
-# Adım 1: Gerçek gereksinim yazın
-echo "# Kullanıcı Doğrulaması
+# 1. Framework'ü başlat (.enderun/ klasörünü oluşturur)
+npx agent-enderun init
 
-JWT tabanlı kimlik doğrulama sistemi kurun.
-- Email/şifre girişi
-- Oturumu kapat endpoint'i
-- Token yenileme mekanizması
-" > docs/requirements.md
+# 2. Bağımlılıkları yükle
+npm install
 
-# Adım 2: Görev oluşturun
-agent-enderun trace:new "Auth Modülü Uygula" backend P1
+# 3. Framework’ü derle
+npm run enderun:build
 
-# Adım 3: Ajanlar sizin için çalışır
-# (Otomatik olarak docs/requirements.md okurlar)
+# 4. Kurulumu doğrula
+npx agent-enderun check
 ```
 
----
-
-## 📁 Proje Yapısı
+> **💡 Özel Adaptör Seçeneği:** İsterseniz belirli bir yapay zeka asistanı veya editör adaptörü ile de başlatabilirsiniz:  
+> `npx agent-enderun init [antigravity | claude | cursor | codex | gemini]`
 
-```
-agent-enderun/
-├── docs/                 ← Ajanların okuyacağı dokümantasyon
-├── packages/
-│   ├── shared-types/     ← Paylaşılan türler (sözleşme)
-│   └── framework-mcp/    ← MCP sunucusu (40+ araç)
-├── apps/                 ← Uygulamalarınız (siz oluşturun)
-├── {{FRAMEWORK_DIR}}/             ← Yönetişim dosyaları
-│   ├── ENDERUN.md        ← Anayasa (OKUNMALI)
-│   ├── PROJECT_MEMORY.md ← Proje durumu
-│   ├── agents/           ← 8 ajan tanımı
-│   ├── logs/             ← Denetim kaydı
-│   ├── knowledge/        ← 16+ rehber
-│   └── docs/api/         ← API sözleşmeleri
-└── bin/
-    └── cli.js            ← CLI giriş noktası
-```
+Adım adım detaylı kurulum rehberi için: [docs/getting-started.md](docs/getting-started.md)
 
 ---
 
-## 💡 Sıkça Sorulan Sorular
-
-### S: "Sözleşme-ilk" ne demek?
-**C:** Tüm API şekilleri ve alan modelleri `packages/shared-types` içinde **kod yazılmadan önce** tanımlanır. Frontend ve backend aynı türleri kullanır.
-
-### S: Ajanlar bütün bunları anlıyor mu?
-**C:** Evet. Her işlem öncesi şunları okurlar:
-1. `ENDERUN.md` (anayasa)
-2. `{{FRAMEWORK_DIR}}/PROJECT_MEMORY.md` (proje durumu)
-3. `docs/` dosyaları (gereksinimler)
-4. `{{FRAMEWORK_DIR}}/knowledge/` (teknik rehberler)
+## 🧠 Dürüst Durum (23 Mayıs 2026)
 
-### S: AI adaptörü kullanmak zorunlu mu?
-**C:** Hayır. Framework, AI'sız da işlev görür. Faz ilerleme, denetim kaydı ve tür disiplini zorunludur.
+**Güçlü Yönler:**
+- Anayasal yönetişim ve zorunlu kurallar sistemi
+- Risk yönetimi ve ajan profesyonelleşme altyapısı
+- Hermes protokolünün teknik temeli ve zorunlu kullanım kuralları
+- Backend tarafında güçlü desenler ve contract-first disiplini
+- Bellek disiplini ve kalıcı denetim kaydı
 
-### S: MCP araçlarını genişletebilir miyim?
-**C:** Evet. `packages/framework-mcp/src/tools/` klasörüne yeni dosya ekleyin.
-
-### S: Kendi ajanlarımı ekleyebilir miyim?
-**C:** Evet. `{{FRAMEWORK_DIR}}/agents/` klasörüne `.md` dosyası oluşturun ve CLI mapping'ini güncelleyin.
-
-### S: Üretim için hazır mı?
-**C:** Framework hazır. `apps/` klasörü tamamen sizin.
+**Hâlâ Geliştirilmesi Gereken Alanlar:**
+- Henüz tam teşekküllü bir referans uygulama bulunmamaktadır (en yüksek öncelik)
+- @frontend henüz hedef olgunluk seviyesine ulaşmamıştır
+- Hermes protokolü henüz gerçek çoklu ajan senaryolarında tam olarak test edilmemiştir
+- Gerçek uzun vadeli kullanım verisi sınırlıdır
+- Mobile ve Native ajanlar erken aşamadadır
 
 ---
 
-## 🔗 Önce Okumanız Gereken Dosyalar
+## 📍 Önümüzdeki Önemli Hedefler
 
-1. **`{{FRAMEWORK_DIR}}/ENDERUN.md`** — Anayasa
-2. **`{{FRAMEWORK_DIR}}/PROJECT_MEMORY.md`** — Proje durumu
-3. **`docs/tech-stack.md`** — Teknoloji kararları
-4. **`packages/shared-types/src/index.ts`** — Sözleşme (türler)
-5. **`README.md`** — Bu dosya
+1. Normal CRUD + Yüksek Riskli Admin işlemi + Hermes kullanımını gösteren gerçek bir referans uygulama kurmak
+2. @frontend Profesyonelleşme Programını tamamlamak (hedef: 9.0)
+3. Hermes Live Test Programını çalıştırıp riski kapatmak
+4. Tüm ajanları minimum 8.0 olgunluk seviyesine çıkarmak
 
 ---
 
-## 📞 Destek & Katkı
-
-### Sorun Bildir
-Net adımlarla ve versiyon numarası ile sorun bildir.
-
-### Katkıda Bulun
-1. `{{FRAMEWORK_DIR}}/ENDERUN.md` oku
-2. Agent rolü yönergelerine uyun
-3. Semantik commit'ler gönder
-4. Testleri geç: `npm run enderun:build`
-
-### Lisans
-MIT © 2026 Yusuf BEKAR
-```bash
-agent-enderun status
-```
-
-### 4. Advanced Intelligence Commands
-```bash
-# Run Security Audit
-agent-enderun check:security
+## 📚 İlgili Dokümanlar
 
-# Generate Dependency Graph
-agent-enderun explorer:graph
-
-# Get Commit Suggestion
-agent-enderun git:commit [TRACE-ID]
-```
-
----
-
-## 📂 Consolidated Framework Structure (`{{FRAMEWORK_DIR}}/`)
-
-All governance and engineering assets are consolidated under the framework directory for a clean project root.
-
-```text
-.
-├── {{FRAMEWORK_DIR}}/
-│   ├── ENDERUN.md           # Supreme Law (Constitution)
-│   ├── PROJECT_MEMORY.md    # Working Memory & History
-│   ├── BRAIN_DASHBOARD.md   # Intelligence & Performance Stats
-│   ├── cli-commands.json    # Agent-to-CLI Mapping
-│   ├── agents/              # 8 Specialized Agent SOPs
-│   ├── knowledge/           # 17+ Enterprise Knowledge Articles
-│   ├── docs/                # API Contracts, Security, Privacy, Strategy
-│   ├── logs/                # Traceable structured JSON logs
-│   ├── benchmarks/          # Performance metrics
-│   └── monitoring/          # System health hooks
-├── bin/                     # CLI Entry Point
-├── packages/                # Shared Types & MCP Engine
-└── apps/                    # Production Modules (Backend, Web, Mobile)
-```
-
----
-
-## 🛡️ Engineering Standards
-
--   **Zero Mock Policy:** Placeholders are forbidden. Every line of code must be functional.
--   **Branded Types:** IDs must be type-safe (e.g., `UserID` vs `string`).
--   **Panda CSS Only:** Zero-runtime CSS-in-JS for high-performance UI.
--   **Contract-First:** Schemas are defined in `shared-types` BEFORE implementation.
+- **[docs/roadmap.md](docs/roadmap.md)** — Risk Takip Panosu ve geliştirme yol haritası
+- **[docs/strategic-review-2026-05.md](docs/strategic-review-2026-05.md)** — Bağımsız stratejik değerlendirme raporu
+- **.enderun/agents/** — 8 ajanın detaylı Standart İş Prosedürleri (SOP)
+- **.enderun/knowledge/** — Uzmanlaşmış teknik ve yönetişim rehberleri
 
 ---
 
-## 📜 License
-MIT © 2026 Yusuf BEKAR — **Agent Enderun: The Future of AI Governance.**
-unctional.
--   **Branded Types:** IDs must be type-safe (e.g., `UserID` vs `string`).
--   **Panda CSS Only:** Zero-runtime CSS-in-JS for high-performance UI.
--   **Contract-First:** Schemas are defined in `shared-types` BEFORE implementation.
-
----
-
-## 📜 License
-MIT © 2026 Yusuf BEKAR — **Agent Enderun: The Future of AI Governance.**
-/                     # CLI Entry Point
-├── packages/                # Shared Types & MCP Engine
-└── apps/                    # Production Modules (Backend, Web, Mobile)
-```
-
----
-
-## 🛡️ Engineering Standards
-
--   **Zero Mock Policy:** Placeholders are forbidden. Every line of code must be functional.
--   **Branded Types:** IDs must be type-safe (e.g., `UserID` vs `string`).
--   **Panda CSS Only:** Zero-runtime CSS-in-JS for high-performance UI.
--   **Contract-First:** Schemas are defined in `shared-types` BEFORE implementation.
+**Agent Enderun yalnızca bir araç değildir.**  
+**Profesyonel, yapay zeka destekli yazılım geliştirme süreçleri için eksiksiz bir işletim sistemidir.**
 
 ---
 
-## 📜 License
-MIT © 2026 Yusuf BEKAR — **Agent Enderun: The Future of AI Governance.**
+**README’nin her iki dili de (English + Türkçe) detaylı ve profesyonel şekilde tamamlandı.**