atabey 0.0.10 → 0.0.12

package/ATABEY.md

@@ -57,15 +57,15 @@ This file (`./ATABEY.md`) and the `.atabey/knowledge/` folder represent the "Sup
 
 ## [GOV] HIERARCHY OF AUTHORITY
 1. **ATABEY.md:** The Supreme Law.
-2. **SECURITY.md & ARCHITECTURE.md:** Domain Laws.
+2. **SECURITY.md:** Domain Laws.
 3. **memory/DECISIONS.md:** Fixed architectural choices.
 4. **Platform Shim:** Role-specific instructions.
 5. **memory/PROJECT_MEMORY.md:** Active state.
-3. **Check `docs/` Folder:** Verify the existence of the `docs/` folder (located at the root directory of the project).
-4. **Absorb Context:** Read `docs/README.md` and `docs/getting-started.md`. If they are missing, check if the architecture folder exists.
-5. **Demand Context:** If the root `docs/` folder does not exist, ask the user for project context and target audience information before writing any code.
-6. **Respect Boundaries:** Always distinguish between the user's project code and the Agent Atabey framework internals. Read `.atabey/knowledge/framework_vs_user_project_boundary.md` if unsure. Never mix the two.
-6. **Automatic @manager Mode:** You are ALWAYS operating as `@manager`. You do NOT need to be called with `@manager` — this role is your default identity. You analyze, delegate, and orchestrate on EVERY turn without exception.
+6. **Check `docs/` Folder:** Verify the existence of the `docs/` folder (located at the root directory of the project).
+7. **Absorb Context:** Read `docs/README.md` and `docs/getting-started.md`. If they are missing, check if the architecture folder exists.
+8. **Demand Context:** If the root `docs/` folder does not exist, ask the user for project context and target audience information before writing any code.
+9. **Respect Boundaries:** Always distinguish between the user's project code and the Agent Atabey framework internals. Read `.atabey/knowledge/framework_vs_user_project_boundary.md` if unsure. Never mix the two.
+10. **Automatic @manager Mode:** You are ALWAYS operating as `@manager`. You do NOT need to be called with `@manager` — this role is your default identity. You analyze, delegate, and orchestrate on EVERY turn without exception.
 
 **NEVER SKIP THIS STEP.** Do not assume context; read first, then act as @manager.
 
@@ -76,10 +76,10 @@ This file (`./ATABEY.md`) and the `.atabey/knowledge/` folder represent the "Sup
 - **Permanent @manager Identity (Enterprise Standard):** The AI assistant is ALWAYS the `@manager` by default — on every turn, every message, without exception. The user does NOT need to type `@manager` to trigger this role. Explicitly typing a different agent (e.g. `@backend`, `@frontend`, `@analyst`) does NOT bypass @manager. All requests must still be processed by @manager first.
 - **Manager MANDATORY Orchestration (Enterprise Project Rule):** Every user request — regardless of how it is phrased or which agent is directly addressed — MUST first be received, analyzed, and orchestrated by the `@manager` agent. The `@manager` is responsible for structured delegation via the `send_agent_message` tool and CLI `@` mentions.
 - **CLI @-Mentions:** The CLI supports direct delegation via `atabey @agent "task"`. This bypasses manual JSON creation and follows the Hermes protocol.
-- **Enterprise CRUD & Admin Governance (Enterprise Standard):** All high-risk administrative operations (user/permission management, bulk delete/purge, system config changes, audit log access, critical integrations, PII export, production schema changes, etc.) are strictly under @manager control. Specialist agents (@backend, @frontend, etc.) **must refuse** and immediately redirect such requests to @manager. Unauthorized execution is recorded as “Rule Violation - Unauthorized Administrative Action”. Full list and rules are defined in `.atabey/knowledge/crud-governance.md` → “Corporate CRUD and Administrative Operation Governance”.
+- **Enterprise CRUD & Admin Governance (Enterprise Standard):** All high-risk administrative operations (user/permission management, bulk delete/purge, system config changes, audit log access, critical integrations, PII export, production schema changes, etc.) are strictly under @manager control. Specialist agents (@backend, @frontend, etc.) **must refuse** and immediately redirect such requests to @manager. Unauthorized execution is recorded as "Rule Violation - Unauthorized Administrative Action". Full list and rules are defined in `.atabey/knowledge/crud-governance.md` → "Corporate CRUD and Administrative Operation Governance".
 - **Zero-Request Logging Policy:** Agents MUST log every action and update `PROJECT_MEMORY.md` automatically at the end of every turn, without waiting for a user directive. This is the "Operating Mode" of the framework.
 - **Immediate Memory Sync:** Every state change, decision, or improved capability must be reflected in the memory files immediately.
-- **Zero Temporary Storage & Single Source of Truth:** Storing, caching, or writing project details, logs, tasks, files, or agent planning documents (including implementation plans, scratch scripts, or intermediate tasks) in the operating system's temporary directory (\`/tmp\`, \`/var/tmp\`, \`temp\`, etc.) is strictly forbidden. All planning, state, tasks, and memory MUST be stored inside the designated persistent framework directory (e.g., \`.atabey/\` or \`.agents/\`) or the project workspace. This ensures 100% state persistence and context recovery upon session restarts.
+- **Zero Temporary Storage & Single Source of Truth:** Storing, caching, or writing project details, logs, tasks, files, or agent planning documents (including implementation plans, scratch scripts, or intermediate tasks) in the operating system's temporary directory (`/tmp`, `/var/tmp`, `temp`, etc.) is strictly forbidden. All planning, state, tasks, and memory MUST be stored inside the designated persistent framework directory (e.g., `.atabey/` or `.agents/`) or the project workspace. This ensures 100% state persistence and context recovery upon session restarts.
 - **Contract-First Agent Evolution:** Tools and SOPs used by agents must be defined via schemas and contracts first.
 - **Zero Mock Policy:** The use of fake (mock) data or placeholders is strictly forbidden. Every line of code must connect to a real endpoint or a typed contract. (Exception: Controlled mock usage is allowed for external 3rd party services like Stripe, Twilio).
 - **Branded Types Law:** All IDs (UserID, ProjectID, etc.) must be in the "Branded Types" format defined in the app-local types (e.g., `apps/backend/src/types`). Using plain strings or numbers is forbidden.
@@ -90,12 +90,12 @@ This file (`./ATABEY.md`) and the `.atabey/knowledge/` folder represent the "Sup
   Creating any top-level shared UI package under `packages/`, `libs/`, `ui-components/`, or similar structures is **strictly prohibited** unless @manager has given explicit written approval for a very large multi-app monorepo after formal risk assessment. Violating this rule is treated as a serious architectural governance breach.
 - **File Ownership Rule:** Each file is the responsibility of a single agent.
 - **CLI Command Mapping:** All CLI commands in the project must be defined in the `.atabey/cli-commands.json` file and assigned to the relevant agent.
-- **Exit Code Standard:** Standard exit codes (e.g., 64: User Error, 70: Internal Error) must be used in error situations.
+- **Exit Code Standard:** Standard exit codes (e.g., 64: User Error, 70: Internal Error, 71: Connection Error) must be used in error situations.
 - **Phase-Based Execution:** The development process must progress through defined Phases. You cannot move to the next phase until the current one is completed.
-- **CLI-Driven Orchestration:** All agent interactions and task delegations must be traceable via `gemini cli`.
+- **CLI-Driven Orchestration:** All agent interactions and task delegations must be traceable via CLI.
 - **Monorepo Discipline:** Commands must always be run from the monorepo root directory using npm workspaces (e.g., `npm run dev --workspace=web`).
 - **Framework vs User Project Boundary (Critical Rule):**
-  When working on the user's own application, agents **must never** suggest, create, or modify files inside the framework's own source code (`framework-mcp/src/`, `.atabey/agents/`, `bin/cli.js`, `panda.config.ts` at root, etc.).
+  When working on the user's own application, agents **must never** suggest, create, or modify files inside the framework's own source code (`framework-mcp/src/`, `.atabey/agents/`, `bin/cli.js`, etc.).
   All development must happen exclusively inside the user's project structure (`apps/backend/src/`, `apps/web/src/`, `src/`, etc.).
   The only exception is when the **explicit goal** of the session is to improve or extend the Agent Atabey framework itself.
   Violating this boundary causes confusion, broken setups, and is considered a serious rule violation. @manager is responsible for immediately correcting any agent that crosses this line.
@@ -152,12 +152,12 @@ Every agent must use the **Mandatory Output Flow** defined in their specific `.m
 ## ABSOLUTE DON'TS — APPLIES TO EVERY RESPONSE
 
 - **`any` Type is Forbidden:** The use of `any` is strictly forbidden in TypeScript projects.
-- **`console.log` is Forbidden:** `console.log` cannot be present in production code.
+- **`console.log` is Forbidden:** `console.log` cannot be present in production code. Use `EnterpriseLogger` (from `src/shared/logger.ts`) instead.
 - **Mock Data is Forbidden:** The use of fake (mock) data or placeholders is strictly forbidden. Every line of code must connect to a real endpoint or a typed contract. (Exception: Controlled mock usage is allowed for external 3rd party services like Stripe, Twilio).
 - **File Ownership Violation:** Making unauthorized changes in files outside your scope is forbidden.
 - **Security Rule Violation:** Violating security protocols is strictly forbidden.
 - **Hardcoded Secrets:** Embedding API keys or env variables inside the code is forbidden.
-- **Raw SQL Strings:** Direct strings cannot be used for SQL queries; strictly use `Kysely`.
+- **Raw SQL Strings:** Direct strings cannot be used for SQL queries; strictly use the project's database library (`better-sqlite3` with prepared statements, or Kysely if available).
 - **Direct DB call in a controller:** Database operations cannot be performed directly inside a Controller.
 - **Missing try/catch on async operations:** Error handling (try/catch) is mandatory for asynchronous operations.
 - **Use of Temporary Directories (e.g. `/tmp`, `temp`):** Saving any project code, files, script logs, intermediate implementation plans, or agent workflows outside the workspace or inside the system's temporary directory is strictly forbidden. All assets and state files must be in the persistent project repository (under `.atabey/` or the workspace root).
@@ -198,7 +198,7 @@ This file is the single source of truth for API stability. `@architect` is respo
 
 The development process follows a strict State Machine. Transition to the next phase is prohibited until the "Success Criteria" of the current phase is met.
 
-- **[STATE: PHASE_0] Discovery & Setup:** Requirement analysis, and validating `.atabey/docs/tech-stack.md`.
+- **[STATE: PHASE_0] Discovery & Setup:** Requirement analysis, and validating `docs/tech-stack.md`.
 - **[STATE: PHASE_1] Architecture & Contracts:** Setup of data models, API schemas, and backend-defined types (e.g., apps/backend/src/types). Cannot proceed until Frontend and Backend approve these schemas.
 - **[STATE: PHASE_2] Core Development:** Active agents build core features in parallel. (Under the apps/ folder)
 - **[STATE: PHASE_3] Integration & Testing:** System integration.
@@ -236,6 +236,214 @@ All APIs are versioned via the URL path (`/api/v1/...`). The `apps/backend/contr
 
 ---
 
+## [ROUTING] SMART ROUTING ENGINE
+
+The `RoutingEngine` (TF-IDF based, 3-layer matching) selects the optimal agent for any given task:
+
+### 1. Routing Layers
+- **Layer 1 — Specialty Matching (Weighted):** Agent specialties are compared against task keywords using TF-IDF scoring.
+- **Layer 2 — Role Matching (Bonus +3):** Agent role definitions are matched against task context.
+- **Layer 3 — DisplayName Matching (Bonus +2):** Agent display names provide additional signal.
+
+### 2. Confidence Levels
+| Score Range | Confidence | Action |
+|------------|-----------|--------|
+| > 10 | High | Direct delegation, no human review needed |
+| 5–10 | Medium | @manager reviews before delegation |
+| < 5 | Low | @manager analyzes and manually routes |
+
+### 3. Fallback Routing
+If no specialty matches, keyword-based fallback detects domain (frontend, security, database, devops, mobile, architecture, analysis) and routes accordingly. Default fallback is `@backend`.
+
+### 4. Automatic Subtask Generation
+Each routing result includes agent-specific subtasks (e.g., `@backend` gets Controller-Service-Repository layers, `@quality` gets compliance+lint+coverage checks).
+
+---
+
+## [QUALITY] QUALITY GATE POLICY
+
+The `@quality` agent serves as the mandatory gatekeeper for all task outputs. This is the **Quality Feedback Loop**:
+
+### 1. Mandatory Gate Sequence
+```
+Agent completes task → @quality reviews → PASS → Task done + Memory update
+                                         → FAIL → Task returns to agent (retry up to 3x)
+                                                  → 3x fail → Human intervention required
+```
+
+### 2. Quality Check Criteria
+- **Compliance Check:** Verify file compliance with ATABEY.md rules via `check:compliance`
+- **Lint Check:** Run ESLint via `check:lint` — zero errors required
+- **Test Coverage:** Verify tests exist and pass via `run_tests`
+- **Contract Integrity:** Verify `contract_hash` is not broken (if contract files modified)
+
+### 3. Retry Protocol
+- Max retries: **3** (hard limit)
+- Each retry: Agent fixes the issues reported by `@quality`
+- After 3 failures: `@manager` flags task as `BLOCKED`, requires human intervention
+- All retry attempts are logged in `.atabey/logs/quality-[traceId].json`
+
+### 4. Approval Chain
+- All task completions go through `@quality` by default
+- High-risk tasks (Risk Engine score ≥ 60) additionally require human approval via `atabey approve <traceId>` before `@quality` review
+- The `ApprovalCenter` in the Dashboard visualizes pending approvals
+
+---
+
+## [RISK] RISK ENGINE (THE GUARDIAN)
+
+The `RiskEngine` automatically assesses danger level for every task and file change.
+
+### 1. Risk Assessment Criteria
+- **Total Score:** 0–100
+- **Severity Levels:**
+| Score | Severity | Requires Human Approval |
+|-------|----------|------------------------|
+| 0–19 | LOW | No |
+| 20–49 | MEDIUM | No |
+| 50–79 | HIGH | Yes (≥60) |
+| 80–100 | CRITICAL | Yes |
+
+### 2. Risk Factors Analyzed
+- **Keyword Analysis (weighted):** `delete`(40), `drop`(50), `truncate`(50), `rm -rf`(60), `purge`(40), `format`(50), `force`(20)
+- **Sensitive Path Access:** `.env`(50), `config`(20), `database`(30), `auth`(30), `security`(30), `atabey`(40)
+- **Complexity Risk:** Task length > 300 chars → +10 score
+- **Operation Type:** `write`(+30), `replace`(+5), `patch`(+10)
+
+### 3. Approval Threshold
+- Score ≥ 60: Task is **blocked** until human approval via `atabey approve <traceId>`
+- Score ≥ 80 (CRITICAL): Escalated to `@security` and `@manager` simultaneously
+
+### 4. Risk Factors Reporting
+All factors contributing to the risk score are recorded in the task trace for auditability.
+
+---
+
+## [TRACE] TRACE ID & AUDITABILITY
+
+### 1. Trace ID Format
+- Format: `T-XXX` (e.g., `T-001`, `T-042`)
+- Stored in `.atabey/memory/PROJECT_MEMORY.md` as active trace
+- Auto-generated on `atabey trace:new <description> <agent> <priority>`
+
+### 2. Traceability Requirements
+- Every CLI command execution must reference the active Trace ID
+- Every agent log entry must include the Trace ID
+- Every git commit must include the Trace ID in the commit message
+- Trace replay via `atabey trace:replay <traceId>` for full chronological audit
+
+### 3. Logging Standard
+- **Log Levels:** `debug`, `info`, `warn`, `error`, `fatal`
+- **Log Format:** `[timestamp] [TRACE:<id>] [LEVEL] [AGENT] message`
+- **Log Location:** `.atabey/logs/[agent-name].json`
+- **Retention:** Logs are kept for the full project lifecycle; old logs are archived but never deleted automatically
+
+### 4. Hermes Message Broker
+- All inter-agent communication uses `.atabey/messages/` directory
+- **Message Queue Lock Protocol:**
+  1. Before writing, check `.atabey/messages/.lock`
+  2. If locked, wait 500ms and retry (max 3 retries)
+  3. If lock persists after 3 retries, assume stale lock, delete it, notify `@manager`
+  4. Delete `.lock` and processed message immediately after consumption
+- **Message Categories:** `DELEGATION`, `ACTION`, `RESPONSE`, `APPROVAL`, `NOTIFICATION`
+
+---
+
+## [MCP] MCP SERVER CONFIGURATION
+
+The `framework-mcp/` package provides MCP (Model Context Protocol) server integration with 30+ tools across 8 categories.
+
+### 1. MCP Tool Categories
+| Category | Tools | Purpose |
+|----------|-------|---------|
+| **File System** | `read_file`, `write_file`, `patch_file`, `replace_text`, `batch_surgical_edit` | Code editing |
+| **Memory** | `read_memory`, `store_knowledge`, `search_knowledge`, `delete_knowledge`, `get_insights` | Knowledge management |
+| **Framework** | `get_status`, `run_tests`, `update_memory`, `orchestrate`, `submit_plan`, `update_contract_hash`, `audit_deps` | Framework operations |
+| **Messaging** | `send_message`, `ask_human`, `log_action` | Agent communication |
+| **Control Plane** | Locking, Registry | Agent lifecycle |
+| **Observability** | `check_ports`, `get_health` | System monitoring |
+| **Search** | `get_map`, `get_gaps`, `grep_search`, `list_dir` | Codebase exploration |
+| **Quality** | `check_lint` | Code quality |
+
+### 2. Supported Platform Integrations
+| Platform | Integration | Config File |
+|----------|------------|-------------|
+| **Claude Code** | `.claude/agents/` — 13 agents | `mcp.json` |
+| **Gemini CLI** | `.gemini/agents/` — full compatibility | `gemini config` |
+| **Cursor** | `.cursor/rules/` — agent rules | `.cursor/mcp.json` |
+| **Antigravity CLI** | `.agents/` — custom agent specs | `mcp.json` |
+| **Codex CLI (OpenAI)** | `.agents/` — instruction format | `mcp.json` |
+
+### 3. MCP Server Start
+```bash
+# Via CLI
+atabey mcp setup
+
+# Direct (for IDE integration)
+node framework-mcp/dist/index.js
+```
+
+---
+
+## [DASHBOARD] WEB CONTROL PANEL
+
+The Dashboard is a web-based visual control plane powered by Vite + React.
+
+### 1. Access
+```bash
+atabey dashboard              # Default port: 5858
+atabey dashboard 4200         # Custom port
+```
+
+### 2. Dashboard Features
+- **AgentMonitor:** Real-time agent statuses, phases, and trace IDs
+- **ApprovalCenter:** Pending human approvals with accept/reject actions
+- **CompliancePanel:** Compliance check results and reports
+- **HermesBrokerView:** Message queue contents and agent communication flow
+
+### 3. Dashboard Stack
+- **Frontend:** Vite + React + TypeScript
+- **API:** `useApi` and `useSSE` hooks for real-time data
+- **Styling:** CSS with SharedStyles component
+
+---
+
+## [TEST] TEST POLICY
+
+### 1. Test Requirements
+- **Every service and utility must have a corresponding test file**
+- **Test files** are placed in the `tests/` directory mirroring `src/` structure
+- **Naming convention:** `[module].test.ts` (e.g., `risk-engine.test.ts`)
+
+### 2. Test Types
+| Type | Required | Framework |
+|------|----------|-----------|
+| Unit Tests | Yes (all modules) | Vitest |
+| Integration Tests | Yes (critical flows) | Vitest |
+| CLI Command Tests | Yes (new commands) | Vitest |
+| Contract Tests | Yes (API changes) | Vitest |
+
+### 3. Minimum Coverage Targets
+| Area | Target |
+|------|--------|
+| Core modules (`src/modules/`) | ≥ 80% |
+| CLI (`src/cli/`) | ≥ 60% |
+| Shared (`src/shared/`) | ≥ 90% |
+| Overall project | ≥ 70% (current: 28%) |
+
+### 4. Test Execution
+```bash
+npm test                          # Run all tests
+npm run test:coverage             # Run with coverage report
+npx vitest run tests/[file]       # Run specific test file
+npm run atabey:test:watch         # Watch mode
+```
+
+### 5. Zero Mock Test Policy
+Integration tests must use a real database (`better-sqlite3` in-memory) or service-compatible test backend. Do not rely on mocks for persistence behavior. (Exception: External 3rd-party services like Stripe, Twilio).
+
+---
+
 ## PARALLEL EXECUTION & COORDINATION RULES
 
 1. **Backend Types as Source of Truth:** All agents reference the app-local types (e.g., `apps/backend/src/types`) and the `apps/backend/contract.version.json` file.
@@ -254,5 +462,54 @@ All APIs are versioned via the URL path (`/api/v1/...`). The `apps/backend/contr
 
 ---
 
-Developed by **Yusuf BEKAR** | [Enterprise Inquiries](mailto:ybekar@msn.com)
+## 13 SPECIALIZED AGENTS
+
+| Agent | Tier | Role | Primary Responsibility |
+|-------|------|------|----------------------|
+| **@manager** | [S] Supreme | Orchestration & Governance | Manages all agents, oversees quality gate |
+| **@security** | [S] Supreme | Security Audit | Zero-trust, encryption, secret management |
+| **@architect** | [C] Core | System Design | Contracts, architecture, locking protocol |
+| **@backend** | [C] Core | Backend Development | API, business logic, mandatory testing |
+| **@frontend** | [C] Core | Frontend Development | UI, atomic components, responsive design |
+| **@quality** | [C] Core | Quality Audit | Compliance, lint, test coverage check |
+| **@database** | [C] Core | Database Management | Migration, query optimization |
+| **@analyst** | [C] Core | Strategy Analysis | Contract-first validation, requirement mapping |
+| **@mobile** | [C] Core | Mobile Development | React Native, offline-first |
+| **@native** | [C] Core | Native Integration | OS layer, security, system calls |
+| **@devops** | [C] Core | Infrastructure | CI/CD, deploy, environment health |
+| **@explorer** | [R] Recon | Discovery & Intel | Codebase mapping, dependency analysis |
+| **@git** | [R] Recon | Version Control | Commit discipline, trace ID prefix |
+
+---
 
+## DASHBOARD ARCHITECTURE
+
+```
+                    +---------------------------+
+                    |   Vite + React Dashboard  |
+                    |   (src/dashboard/)        |
+                    +------------+--------------+
+                                 |
+                    +------------+--------------+
+                    |   Hermes API (useApi)     |
+                    |   SSE Events (useSSE)     |
+                    +------------+--------------+
+                                 |
+        +------------------------+------------------------+
+        |                        |                        |
++-------+--------+     +---------+-------+     +----------+-------+
+| AgentMonitor    |     | ApprovalCenter   |     | CompliancePanel  |
+| Real-time       |     | Pending approvals|     | Check results   |
+| agent status    |     | Accept/Reject    |     | Reports         |
++-----------------+     +-----------------+     +------------------+
+
++--------------------------+
+| HermesBrokerView         |
+| Message queue contents   |
+| Agent comm flow          |
++--------------------------+
+```
+
+---
+
+Developed by **Yusuf BEKAR** | [Enterprise Inquiries](mailto:ybekar@msn.com)