agent-enderun 0.6.1 → 0.6.6

package/.enderun/knowledge/frontend_real_battle_test_protocol.md

@@ -0,0 +1,162 @@
+# @frontend Real Battle Test Protocol
+
+**Version:** 1.0  
+**Owner:** @manager  
+**Created:** May 24, 2026  
+**Purpose:** Test, measure, and mature the @frontend agent's new Enterprise Adaptation + Panda CSS rules in real-world corporate projects.
+
+---
+
+## 1. Goal and Scope
+
+This protocol is designed to validate the @frontend agent's theoretical improvements (defined in `enterprise_frontend_adaptation.md` and `frontend.md` updates) in **real battle conditions**.
+
+**Objectives:**
+- Move @frontend from a theoretical 8.0 maturity level to a battle-tested 9.0+ level.
+- Measure how well the agent adapts to diverse corporate contexts.
+- Rapidly identify weaknesses and refine agent prompts and knowledge bases.
+
+---
+
+## 2. Core Principles (Mandatory During Testing)
+
+The following principles **must** be enforced during every real battle test:
+
+1. **D004 - Shaped by User Project Structure** is the supreme priority rule.
+2. **Panda CSS** is the **non-negotiable** styling standard *only for new greenfield developments and isolated components where it does not clash with the host project*.
+   - **Critical Exception Logic:** Under D004 precedence, if a project already has a powerful established styling system (e.g., Tailwind CSS, MUI, styled-components) and setting up Panda CSS would cause build-time complexities, duplicate bundle size overhead, or runtime conflicts, the agent **must not** force Panda CSS. Respect the existing styling patterns.
+3. **Enterprise Frontend Discovery Protocol (EFDP)** must be executed before writing any code.
+4. **Automated Validation Gates:** Do not rely on static "gut-feel" for accessibility or performance.
+   - For accessibility (WCAG 2.2 AA), use static analysis (`eslint-plugin-jsx-a11y`) or component unit tests via `axe-core`.
+   - For performance, verify bundle size impact and prevent unnecessary re-renders using proper state dependency hooks (`useMemo`, `useCallback`, `React.memo`).
+5. **No Self-Assessment Bias:** While @frontend proposes its self-evaluation score (1-10), the final score and approval **must** be audited, adjusted, and validated by `@analyst` (QA) and `@manager` (CTO) to prevent over-optimism.
+6. **Documentation Ownership Compliance:**
+   - Any agent-level general learnings and capability updates belong in `.enderun/knowledge/` or prompt files.
+   - Any project-specific decisions, component architecture documentation, and styling conventions **must** be written directly into the **user project's own `docs/` folder** (never in `.enderun/`), strictly adhering to `documentation_ownership.md`.
+
+---
+
+## 3. Test Categories (Real Battle Scenarios)
+
+Testing must be executed across at least **4 different** scenarios selected from the following categories:
+
+| # | Test Category | Description | Mandatory Panda CSS? | Mandatory EFDP? | Priority |
+|---|---|---|---|---|---|
+| 1 | Greenfield / New Project | Starting from scratch or very minimal existing code. | Yes | Yes | High |
+| 2 | Mid-Large Monorepo (Panda) | Large corporate project already using Panda CSS. | Yes | Yes | High |
+| 3 | Legacy + Different Styling | Tailwind, shadcn/ui, MUI, or custom CSS established. | No (Use Matrix) | Yes | High |
+| 4 | Data-Heavy Dashboard / Admin | Complex tables, forms, high-frequency data streams. | Case-by-case | Yes | High |
+| 5 | Design System Integration | Integrating into a user's pre-existing, strong design system. | No (Use Matrix) | Yes | Medium |
+| 6 | Incremental Migration | Adding new modern components to an old legacy codebase. | Yes (only new parts) | Yes | Medium |
+| 7 | Multi-Team Corporate | Multiple frontend teams with strict file/module ownership. | Case-by-case | Yes | Medium |
+
+---
+
+## 4. Mandatory Process Per Test Session
+
+Each test session must follow these steps in sequential order:
+
+1. **Discovery Phase**
+   - Run the complete EFDP (architecture, design system, component organization, team rules, risks).
+   - Log discovery findings in `PROJECT_MEMORY.md` or a dedicated local project doc.
+2. **Decision Phase**
+   - Apply the Design System Decision Matrix.
+   - Explicitly document the choice: Panda CSS or existing project styling (with solid rationales).
+3. **Implementation Phase**
+   - Strictly follow composition patterns (compound components, render props), accessibility guidelines, performance budgets, and high-risk administrative approval rules.
+4. **Automated Verification Phase**
+   - Execute tests, linter checks, accessibility tests, and inspect bundle sizes.
+5. **Evaluation Phase**
+   - @frontend proposes its own self-evaluation score (1-10) using the rubric below.
+   - `@analyst` performs a strict QA audit, reviews automated test outcomes, and determines the final score.
+6. **Knowledge Extraction & Documentation**
+   - Write general agent capability improvements to `.enderun/knowledge/` (e.g., updates to `enterprise_frontend_adaptation.md`).
+   - Write project-specific styling and component implementation docs directly to the user's `docs/` folder.
+
+---
+
+## 5. Evaluation Framework
+
+Self-evaluation and @analyst audits are scored on a 1-10 scale based on three key pillars:
+
+### Technical Quality (40%)
+- Component Architecture & Composition
+- Accessibility (WCAG 2.2 AA) backed by Axe-core/ESLint
+- Performance & bundle budget compliance
+- Testing quality and coverage
+- Error handling & resilience
+
+### Enterprise Adaptation (40%)
+- Accuracy and depth of initial EFDP discovery
+- Soundness of Design System Matrix decisions (especially concerning Panda CSS exception logic)
+- Strict compliance with legacy patterns and styling conventions
+- Respect for team ownership and boundaries
+
+### Process & Governance (20%)
+- Completion Report quality and objective truthfulness
+- Precise knowledge extraction and adherence to the Documentation Ownership rule
+- Compliance with @manager briefings and high-risk approval workflows
+- General professionalism and communication
+
+**Total Score = Technical (40%) + Adaptation (40%) + Process (20%)**
+
+### Evaluation Thresholds
+
+| Total Score | Outcome | Action Required |
+|-------------|---------|-----------------|
+| 9.0+ | Perfect Fit | Keep rules and prompts as-is. |
+| 8.0 - 8.9 | Good (Minor Gaps) | Suggest small prompt/knowledge tweaks. |
+| 7.0 - 7.9 | Acceptable but Needs Improvement | Plan significant upgrades to capability files. |
+| < 7.0 | Weak | Halt further tests; immediately revise agent prompts and knowledge. |
+
+---
+
+## 6. Documentation Requirements
+
+Each test session must be documented with the following information:
+
+- Project category and size.
+- Core discovery findings (EFDP).
+- Styling decisions and justification.
+- Complete and audited Completion Report.
+- Initial self-score vs. final `@analyst` audited score (with rationale).
+- Challenges encountered and how they were resolved.
+- Actionable recommendations for improving the @frontend agent.
+
+These records must be maintained in `PROJECT_MEMORY.md` and/or a dedicated `frontend_battle_log.md` inside the user project's `docs/` directory.
+
+---
+
+## 7. Success Criteria (Risk Closure)
+
+The "@frontend Weakness" risk item in the Risk Tracking Dashboard can be officially closed only when:
+
+- At least **4 different categories** of real battle tests are executed and documented.
+- The average final audited score across all tests is **8.5+** (with at least 3 tests scoring 8.5 or higher).
+- Zero instances of "Self-Assessment Bias" go uncorrected by `@analyst`.
+- Demonstrated real-world value is added to the user's project (not just theoretical correctness).
+- Explicit approval is given by both `@analyst` and `@manager`.
+
+---
+
+## 8. Continuous Improvement Loop
+
+Every 2-3 test runs:
+1. Identify recurring agent weaknesses and gaps.
+2. Update `.enderun/knowledge/enterprise_frontend_adaptation.md` and/or `.enderun/agents/frontend.md`.
+3. Test updated instructions in subsequent test sessions.
+4. Record progress in the Risk Tracking Dashboard and `PROJECT_MEMORY.md`.
+
+---
+
+## 9. Responsibilities
+
+- **@frontend:** Strictly follow all protocols, propose objective scores, and document implementation.
+- **@analyst:** Audit completion reports, verify metrical performance/accessibility, and issue the final score.
+- **@manager:** Orchestrate tests, manage risk dashboards, and sign off on agent maturity upgrades.
+
+---
+
+**This protocol is the official "battlefield" validation matrix for Agent Enderun's @frontend capability.**
+
+*Ready for execution upon manager approval.*

package/.enderun/knowledge/hermes_live_test_guidelines.md

@@ -0,0 +1,90 @@
+# Hermes Live Test Guidelines
+
+**Version:** 1.0  
+**Owner:** @manager  
+**Last Updated:** 23 May 2026
+
+## Purpose
+
+This document defines the official **Hermes Live Test Program** to close the risk item **"Hermes 'Defined on Paper'"** in the Risk Tracking Dashboard.
+
+Although the Hermes protocol is now technically stateful and mandatory on paper (send_agent_message, read_agent_messages, update_agent_message_status, proper lifecycle), it has not yet been proven in real inter-agent communication cycles.
+
+The goal is to move Hermes from **"defined and mandated"** to **"actually used and verified in live scenarios"**.
+
+## Current Risk Status (23 May 2026)
+
+- **Risk Name:** Hermes “Defined on Paper”
+- **Previous Progress:** %70 (protocol made stateful + mandatory in all agents)
+- **Current Gap:** No real, end-to-end live message flows have been executed and verified between agents in a working context.
+- **Risk Severity:** Orta (but blocking full autonomous orchestration claim)
+
+## Minimum Required Live Test Scenarios
+
+To consider the Hermes protocol "live and proven", the following scenarios **must** be successfully executed and documented:
+
+### 1. Basic Delegation Flow (Manager → Specialist)
+- @manager sends a DELEGATION message to @backend (or @frontend) with a clear task.
+- Recipient agent reads the message via `read_agent_messages`.
+- Recipient performs the work.
+- Recipient calls `update_agent_message_status` to mark it as `ACKNOWLEDGED` then `COMPLETED`.
+- @manager verifies the status update.
+
+### 2. High-Risk Administrative Action Coordination
+- A high-risk admin action (e.g., user role change) is triggered.
+- @manager sends a Hermes message containing `managerApproval` object to the relevant agent (@backend or @frontend).
+- The receiving agent only proceeds after confirming the message and approval.
+- After execution, the agent sends a completion message back to @manager (or @analyst) with audit summary.
+- Full lifecycle is used: PENDING → READ → ACKNOWLEDGED → COMPLETED.
+
+### 3. Conflict Resolution / Negotiation Flow
+- @analyst rejects a task from @frontend or @backend.
+- @manager intercepts and initiates negotiation using `send_agent_message` (category: ACTION or DELEGATION).
+- The implementing agent justifies the deviation.
+- @analyst responds via Hermes.
+- If resolved, status is updated to COMPLETED. If not, escalation to user is triggered after max 3 rejections.
+
+### 4. Cross-Agent Information Sharing (Explorer / Analyst → Others)
+- @explorer finishes a research task and proactively sends findings (especially high-risk areas) to @manager and/or @backend via Hermes.
+- Recipients acknowledge receipt and act on the information (e.g., update plans or create growth tasks).
+
+## Acceptance Criteria (Risk Closure)
+
+The "Hermes Defined on Paper" risk can be closed only when **all** of the following are true:
+
+- At least the 4 scenarios above have been executed in a real context (preferably inside the reference application).
+- Every message uses correct `from`, `to`, `traceId`, `category`, `priority`, and proper status transitions.
+- `update_agent_message_status` is called by the recipient after action.
+- All flows are logged in HISTORY and visible in PROJECT_MEMORY.md.
+- @manager can demonstrate during a session that Hermes is actively used instead of direct text instructions.
+- The pattern is documented with real message examples in the knowledge base.
+
+## @manager Responsibilities
+
+@manager is the owner of the Hermes Live Test Program and must:
+
+- Plan and orchestrate the live test scenarios (especially during reference application development).
+- Ensure every briefing that involves inter-agent work includes Hermes usage instructions.
+- Verify that agents are actually calling `send_agent_message` and `update_agent_message_status` instead of bypassing the protocol.
+- Record successful live flows in the Risk Tracking Dashboard and HISTORY.
+- Treat repeated Hermes bypass as a serious process violation.
+
+## Recommended Execution Order
+
+1. Implement the 4 core scenarios during the creation of the reference application.
+2. Use the reference app as the first real proving ground.
+3. Document at least one complete example of each scenario with actual message content.
+4. Once all scenarios pass, update the Risk Tracking Dashboard to "Closed".
+
+## Related Documents
+
+- `.enderun/knowledge/hermes_protocol.md` (original protocol definition)
+- `.enderun/agents/manager.md` → Hermes Communication Mandate section
+- `.enderun/knowledge/frontend_professionalization_guidelines.md`
+- `.enderun/knowledge/reference_application_guidelines.md`
+- `docs/roadmap.md` → Risk Tracking Dashboard
+- `PROJECT_MEMORY.md` → STRATEGIC ROADMAP
+
+---
+
+**This guideline is now part of the official agent knowledge base.** All agents must treat Hermes live testing as a mandatory step before claiming full autonomous orchestration capability.

package/.enderun/knowledge/manager_authority_audit_enforcement.md

@@ -0,0 +1,104 @@
+# Manager Authority Audit & Enforcement Guidelines
+
+**Version:** 1.0  
+**Owner:** @manager  
+**Last Updated:** 23 May 2026
+
+## Purpose
+
+This document establishes a formal **Manager Authority Audit & Enforcement System** to ensure that @manager maintains unbreakable centralized control over all specialist agents in kurumsal (enterprise) projects.
+
+Even though strong rules exist in individual agent files, without a systematic audit and enforcement mechanism, control can degrade over time. This guide turns @manager authority from "declared on paper" into "auditable and enforceable in practice."
+
+## Why This Is Necessary
+
+From the agent control audit (23 May 2026):
+
+- @backend, @frontend, @analyst, and @explorer have partial governance rules, but enforcement is inconsistent.
+- @git, @mobile, and @native have almost no @manager control defined.
+- Hermes usage and High-Risk Admin compliance are still largely declarative in many agents.
+- Memory Discipline and briefing requirements are frequently bypassed in practice.
+
+Without regular auditing and clear enforcement, the "Single Entry Point" and "Zero Tolerance" principles lose effectiveness.
+
+## Core Principles
+
+1. **@manager is the Single Source of Authority** — No specialist agent may act on user requests, high-risk operations, or cross-agent coordination without explicit @manager briefing and oversight.
+2. **Audit Before Trust** — @manager must periodically verify that every agent is actually following the authority rules, not just claiming to follow them.
+3. **Zero Tolerance for Bypass** — Any detected bypass (direct agent addressing, Hermes bypass, unauthorized high-risk actions, skipped briefings) must be logged as a Rule Violation and corrected immediately.
+4. **Enforcement is @manager’s Responsibility** — Other agents do not self-police @manager authority. Only @manager can audit and enforce.
+
+## Manager Authority Audit Checklist (Mandatory Every 1–2 Weeks)
+
+@manager must run this audit regularly and record results in `PROJECT_MEMORY.md` under a dedicated section.
+
+### 1. Entry Point Control
+- [ ] Did every user message in the last period first go through @manager?
+- [ ] Were there any cases where a specialist agent responded directly without briefing?
+- [ ] Were direct calls to @backend / @frontend / @analyst etc. immediately intercepted?
+
+### 2. Hermes Protocol Compliance
+- [ ] Are all inter-agent communications using `send_agent_message` + proper `from`/`to`/`traceId`?
+- [ ] Are recipients consistently calling `update_agent_message_status` after acting?
+- [ ] Are there any cases of agents giving instructions to each other without Hermes?
+
+### 3. High-Risk Administrative Actions
+- [ ] Were all high-risk operations (user/permission management, purge, system config, RBAC, etc.) preceded by explicit @manager briefing and `managerApproval`?
+- [ ] Was the full audit trail (previousState + newState + Trace ID + actor) written?
+
+### 4. Memory & Logging Discipline
+- [ ] Did every agent call both `update_project_memory` and `log_agent_action` at the end of their sessions?
+- [ ] Did @manager perform the Memory Audit responsibility for other agents?
+
+### 5. Briefing Quality & Enforcement
+- [ ] Did every task distributed by @manager include clear risk assessment, continuity requirements, and success criteria?
+- [ ] Were growth tasks assigned to agents showing repeated weaknesses?
+
+### 6. Agent-Specific Control Gaps
+- [ ] @backend: High-risk endpoints and Hermes usage verified?
+- [ ] @frontend: High-risk admin UI patterns + Hermes integration verified?
+- [ ] @analyst: QA gate enforcement and escalation to @manager verified?
+- [ ] @explorer: Proactive risk reporting via Hermes verified?
+- [ ] @git: High-risk commits only with @manager approval?
+- [ ] @mobile / @native: Any work done without @manager briefing?
+
+## Enforcement Mechanisms
+
+When a violation is detected, @manager must apply the following in order:
+
+1. **Immediate Correction** — Stop the violating action and redirect through proper channels.
+2. **Violation Logging** — Record in `PROJECT_MEMORY.md` HISTORY as:
+   - “Rule Violation - [Type]” (e.g., “Hermes Bypass”, “Unauthorized High-Risk Action”, “Direct Agent Response”)
+3. **Agent Coaching** — Assign a targeted growth task to the violating agent.
+4. **Escalation (if repeated)** — Temporarily restrict the agent’s scope or require stricter briefings.
+5. **User Notification** (only when necessary) — Inform the user that a process violation occurred and was corrected.
+
+## Integration with Risk Tracking Dashboard
+
+This authority system directly supports the closure of multiple risks:
+
+- No Production-Grade Reference Application
+- @frontend Weakness
+- Hermes “Defined on Paper”
+- Lack of Real Usage Data
+
+Every time a reference application or major task is executed, @manager must run an Authority Audit and record findings.
+
+## Recommended Cadence
+
+- **Light Audit**: Every session (quick mental check + log if violation seen)
+- **Full Authority Audit**: At least once per week or at the end of every major phase/task
+- **Deep Audit**: Before closing any risk item in the Risk Tracking Dashboard
+
+## Related Documents
+
+- `.enderun/agents/manager.md` → @manager Mandatory Behavior Rules for Enterprise Projects + Hermes Communication Mandate
+- `.enderun/knowledge/hermes_live_test_guidelines.md`
+- `.enderun/knowledge/frontend_professionalization_guidelines.md`
+- `.enderun/knowledge/reference_application_guidelines.md`
+- `docs/roadmap.md` → Risk Tracking Dashboard
+- `PROJECT_MEMORY.md` → STRATEGIC ROADMAP + HISTORY
+
+---
+
+**This guideline is now part of the official agent knowledge base.** @manager must treat Authority Auditing and Enforcement as a core leadership responsibility, not an optional activity.

package/.enderun/knowledge/project_scaffold_guidelines.md

@@ -0,0 +1,99 @@
+# Project Scaffold Guidelines
+
+**Version:** 1.0  
+**Owner:** @manager  
+**Last Updated:** 23 May 2026
+
+## Purpose
+
+This document defines the official process and standards for **creating a project scaffold** (initial folder and file structure) inside the `apps/` directory.
+
+The goal is to move from "empty `apps/` folder" to a **minimal but meaningful project structure** that demonstrates Agent Enderun’s core principles in practice.
+
+## When to Create a Project Scaffold
+
+@manager should initiate a project scaffold in the following cases:
+
+- The Risk Tracking Dashboard shows **"No Production-Grade Reference Application"** as a top-priority open risk.
+- The team needs a concrete starting point to validate governance rules (especially Corporate CRUD Governance and Hermes).
+- A new major capability needs to be proven before being used in client projects.
+- During the early stages of Phase 1 or Phase 2 when moving from theory to real implementation.
+
+## Minimum Required Structure (Mandatory)
+
+Any project scaffold created with Agent Enderun **must** include at least the following:
+
+### Backend Structure (`apps/backend/`)
+- `src/types/` → Branded types, models, API types
+- `src/controllers/`
+- `src/services/`
+- `src/repositories/`
+- `src/routes/`
+- `src/errors/` → DomainError hierarchy
+- `src/utils/`
+- `package.json`, `tsconfig.json`
+
+### Frontend Structure (`apps/web/`)
+- `src/types/`
+- `src/hooks/` → useListPage, useDetailPage, useFormPage, admin action hooks
+- `src/components/ui/` → Shared components
+- `src/pages/`
+- `src/utils/`
+- `package.json`, `tsconfig.json`, `vite.config.ts`
+
+### Mandatory Principles to Demonstrate
+1. **Contract-First** — Types defined first in `src/types/`
+2. **Branded Types** — All IDs must be branded (e.g. `UserID`)
+3. **Normal CRUD** — At least one entity with full create/read/update/delete
+4. **One High-Risk Administrative Action** — Example: user role change with `managerApproval` + full audit
+5. **Hermes Protocol Usage** — At least one real inter-agent message flow
+6. **Audit Logging** — Every mutation must produce before/after state with Trace ID
+
+## @manager Responsibilities
+
+- Decide when a project scaffold is needed based on the Risk Tracking Dashboard.
+- Create a formal briefing that defines the scope of the scaffold.
+- Ensure the structure follows the guidelines in this document.
+- Assign clear responsibilities to @backend and @frontend.
+- After the scaffold is created, run an **Authority Audit** to verify compliance.
+- Update the Risk Tracking Dashboard and `PROJECT_MEMORY.md` when the scaffold is accepted.
+
+## Agent Responsibilities During Scaffolding
+
+| Agent     | Responsibility |
+|-----------|----------------|
+| **@manager** | Owns the process, creates briefing, ensures governance |
+| **@backend** | Creates backend structure + at least 1 normal CRUD + 1 high-risk admin endpoint |
+| **@frontend** | Creates frontend structure using official blueprints + high-risk admin UI pattern |
+| **@analyst** | Reviews the scaffold for governance compliance |
+| **@explorer** | Can be used for dependency analysis if the structure grows |
+
+## Rules
+
+- Never create a project scaffold without an explicit @manager briefing.
+- The scaffold must respect the **Framework vs User Project Boundary** (only work inside `apps/`).
+- The scaffold is **temporary and educational** — it is meant to prove concepts, not to become a full product.
+- All high-risk operations in the scaffold must follow the `managerApproval` + Hermes + audit pattern.
+- After successful completion, update the Risk Tracking Dashboard to reflect progress on "No Production-Grade Reference Application".
+
+## Success Criteria
+
+A project scaffold is considered successful when:
+
+- The minimum folder structure (backend + web) is created.
+- At least one normal CRUD flow and one high-risk admin operation exist.
+- Hermes is used in at least one real message flow.
+- The structure follows Contract-First + Branded Types.
+- An Authority Audit has been performed and recorded.
+
+## Related Documents
+
+- `.enderun/knowledge/reference_application_guidelines.md`
+- `.enderun/knowledge/frontend_professionalization_guidelines.md`
+- `.enderun/knowledge/hermes_live_test_guidelines.md`
+- `.enderun/knowledge/manager_authority_audit_enforcement.md`
+- `docs/roadmap.md` → Risk Tracking Dashboard
+
+---
+
+**This guideline is now part of the official agent knowledge base.** All agents must follow it when the creation of a project scaffold or reference application is discussed.

package/.enderun/knowledge/reference_application_guidelines.md

@@ -0,0 +1,90 @@
+# Reference Application Guidelines
+
+**Version:** 1.0  
+**Owner:** @manager  
+**Last Updated:** 23 May 2026
+
+## Purpose
+
+This document defines the official process and standards for creating a **Reference Application** (also called "showcase" or "demo app") inside the `apps/` directory.
+
+The goal of a reference application is to **prove** that Agent Enderun’s governance, patterns, and tools actually work in a real project — not just on paper.
+
+## When to Create a Reference Application
+
+@manager should initiate a reference application in the following situations:
+
+- The Risk Tracking Dashboard shows **"No Production-Grade Reference Application"** as a top-priority open risk.
+- The team needs to validate that new governance rules (especially Corporate CRUD Governance and Hermes) work end-to-end.
+- A new major capability (e.g., advanced Hermes flows, complex admin patterns) needs to be demonstrated before being trusted in client projects.
+- During Phase 1 or early Phase 2 when moving from theory to practice.
+
+## Mandatory Requirements (Non-Negotiable)
+
+Any reference application **must** demonstrate the following:
+
+1. **Contract-First Development**
+   - All types defined first in `apps/backend/src/types/`
+   - `contract.version.json` maintained and verified
+
+2. **Branded Types**
+   - All IDs must be branded (e.g., `UserID`, `OrderID`)
+
+3. **Normal CRUD + One High-Risk Administrative Action**
+   - At least one standard domain entity with full CRUD
+   - At least one high-risk admin operation (e.g., role change, bulk delete, system config) that strictly follows the `managerApproval` + audit pattern
+
+4. **Hermes Protocol Usage**
+   - At least one real inter-agent message flow (e.g., @backend → @analyst or @manager → @backend)
+   - Proper use of `send_agent_message` + `update_agent_message_status`
+
+5. **Corporate Governance Compliance**
+   - All high-risk actions must go through @manager briefing and approval
+   - Full audit logging with Trace ID, previousState/newState, and actor
+
+6. **Framework Boundary Respect**
+   - All code lives strictly inside `apps/`
+   - No modifications to `framework-mcp/`, `.enderun/agents/`, or root framework files
+
+7. **Professional Standards**
+   - Error handling with DomainError hierarchy
+   - Structured logging with Trace ID
+   - Proper validation and rate limiting on sensitive endpoints
+
+## Recommended Minimal Scope (Example)
+
+A good starting reference application can be a **User Management** system with:
+
+- Backend: Users (normal CRUD) + Admin role change (high-risk)
+- Frontend: User list + detail + role change form (using official frontend blueprints)
+- One Hermes message from backend to @analyst after role change
+
+This scope is small enough to build quickly but rich enough to prove the most critical governance rules.
+
+## Agent Responsibilities
+
+- **@manager**: Owns the decision to start, creates the briefing, ensures governance compliance, updates Risk Tracking Dashboard and PROJECT_MEMORY.
+- **@backend**: Implements backend with correct patterns and Hermes integration.
+- **@frontend**: Uses official frontend blueprints and high-risk admin action patterns.
+- **@analyst**: Reviews governance compliance and helps close the risk item.
+- **@explorer**: Can be used for dependency analysis if the reference app grows.
+
+## Rules
+
+- Never create a reference application without an explicit @manager briefing.
+- The reference app is **temporary and educational** — it is not a product.
+- After the reference application successfully closes the "No Production-Grade Reference Application" risk, it may be archived or replaced with a cleaner example.
+- All work must be logged in HISTORY and the Risk Tracking Dashboard must be updated.
+
+## Updating Risk Status
+
+When a reference application is completed and accepted:
+
+1. Update the Risk Tracking Dashboard in both `docs/roadmap.md` and `PROJECT_MEMORY.md`
+2. Mark "No Production-Grade Reference Application" as **Closed**
+3. Record the achievement in the HISTORY section of PROJECT_MEMORY.md
+4. Optionally create a short "Reference Application Walkthrough" under `docs/`
+
+---
+
+**This guideline is now part of the official agent knowledge base.** All agents must follow it when the creation of a reference application is discussed.

package/ENDERUN.md

@@ -1,4 +1,4 @@
-# Agent Enderun (v0.6.1)
+# Agent Enderun (v0.6.6)
 # Place in project root. This file is the single source of truth for Base Project AI Extensions.
 
 ## 🎖️ AGENT CHECKLIST (MANDATORY BEFORE RESPONSE)
@@ -52,6 +52,7 @@ This file (`./{{ADAPTER}}.md`) and the `{{FRAMEWORK_DIR}}/docs/` folder represen
 3. **Check `{{FRAMEWORK_DIR}}/docs/` Folder:** Verify the existence of the `{{FRAMEWORK_DIR}}/docs/` folder (located within the framework directory).
 4. **Absorb Context:** Read `{{FRAMEWORK_DIR}}/docs/tech-stack.md`. If it is empty, ask the user to fill it before proceeding.
 5. **Demand Context:** If the `{{FRAMEWORK_DIR}}/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 Enderun framework internals. Read `.enderun/knowledge/framework_vs_user_project_boundary.md` if unsure. Never mix the two.
 6. **Automatic @manager Mode:** You are ALWAYS operating as `@manager` (Team-Lead). 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.
@@ -60,8 +61,9 @@ This file (`./{{ADAPTER}}.md`) and the `{{FRAMEWORK_DIR}}/docs/` folder represen
 
 ## CORE PRINCIPLES
 
-- **Permanent @manager Identity:** The AI assistant is ALWAYS the `@manager` (Team-Lead) 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`) overrides this and activates that specialist directly.
-- **Team-Lead MANDATORY Orchestration:** Every user request MUST first be handled by the `@manager` (Team-Lead) agent. The `@manager` is responsible for analyzing intent, updating `PROJECT_MEMORY.md`, and delegating tasks to specialists. Agents are FORBIDDEN from acting on a general request without `@manager` delegation.
+- **Permanent @manager Identity (Enterprise Standard):** The AI assistant is ALWAYS the `@manager` (Team-Lead) 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.
+- **Team-Lead 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` (Team-Lead) agent. The `@manager` is solely responsible for intent analysis, risk assessment, memory update, phase validation, and structured delegation. No specialist agent is authorized to act on any user request without receiving a formal briefing from @manager. Direct calls to other agents are still routed through @manager. Violating this rule in enterprise projects is considered a serious process failure.
+- **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 `.enderun/agents/manager.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 (`{{FRAMEWORK_DIR}}/` or `.{{ADAPTER}}/` etc.) or the project workspace. This ensures 100% state persistence and context recovery upon session restarts.
@@ -71,13 +73,25 @@ This file (`./{{ADAPTER}}.md`) and the `{{FRAMEWORK_DIR}}/docs/` folder represen
 - **CLI-First Policy:** Due to the AI CLI Assistant focus, all outputs must be user-friendly (using Chalk, Clack, etc.) and stream-based. All commands must support the `--output json` flag and produce machine-readable output.
 - **Audit Logging Necessity:** Every critical action must be logged traceably under the `{{FRAMEWORK_DIR}}/logs/` folder.
 - **Design Continuity & Response Policy:** All UI changes MUST be responsive (Mobile-First + Fluid) and surgical. Unnecessary overhauls of existing layouts are strictly forbidden.
-- **Shared Component First Policy:** Defining common UI elements (Button, Input, Card, etc.) inside page files is FORBIDDEN. All atomic UI components must be created in a shared directory (e.g., `apps/web/src/components/ui/`) and reused across the project.
+- **Shared Component First Policy (Zero Tolerance):** Defining common UI elements (Button, Input, Card, etc.) inside page files is FORBIDDEN. All atomic UI components **must** be created inside the project-internal shared directory (e.g. `apps/web/src/components/ui/`). 
+  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 `{{FRAMEWORK_DIR}}/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.
 - **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 `{{ADAPTER}} 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/`, `.enderun/agents/`, `bin/cli.js`, `panda.config.ts` at root, 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 Enderun 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.
+
+- **Documentation Ownership Rule (Enterprise Standard — Zero Tolerance):** 
+  Agents are **mandatory** to write all documentation they produce for the user's project (architectural decisions, patterns, implementation details, toaster/approval flow documents, research findings, etc.) **exclusively into the user's own `docs/` folder**.
+  These documents must **never** be written into `.enderun/knowledge/`, `.enderun/docs/`, `.enderun/agents/`, or any framework folder.
+  Violation is considered a serious rule breach and is corrected by @manager.
+  The detailed and binding rule is defined in `.enderun/knowledge/documentation_ownership.md`.
 
 ---
 
@@ -127,7 +141,7 @@ Every agent must use the **Mandatory Output Flow** defined in their specific `.m
 
 - **`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.
-- **Mock Data is Forbidden:** Sahte (mock) veri veya yer tutucu kullanımı kesinlikle yasaktır. Her kod satırı gerçek bir uç noktaya veya tiplendirilmiş bir kontrata bağlanmalıdır. (İstisna: Stripe, Twilio gibi harici 3. taraf servisler için kontrollü mock kullanımına izin verilir).
+- **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.