agent-enderun 1.1.4 → 1.1.5

package/src/shared/container.ts

@@ -0,0 +1,67 @@
+import { ValidationError } from "./errors.js";
+
+export type FactoryFunction<T> = (container: ServiceContainer) => T;
+
+export class ServiceContainer {
+    private static instance: ServiceContainer;
+    private services: Map<string, unknown> = new Map();
+    private factories: Map<string, FactoryFunction<unknown>> = new Map();
+
+    private constructor() {}
+
+    public static getInstance(): ServiceContainer {
+        if (!ServiceContainer.instance) {
+            ServiceContainer.instance = new ServiceContainer();
+        }
+        return ServiceContainer.instance;
+    }
+
+    /**
+     * Registers a pre-instantiated singleton service.
+     */
+    public register<T>(name: string, service: T): void {
+        if (this.services.has(name)) {
+            throw new ValidationError(`Service '${name}' is already registered.`);
+        }
+        this.services.set(name, service);
+    }
+
+    /**
+     * Registers a factory function for lazy evaluation.
+     */
+    public registerFactory<T>(name: string, factory: FactoryFunction<T>): void {
+        if (this.factories.has(name) || this.services.has(name)) {
+            throw new ValidationError(`Service or factory '${name}' is already registered.`);
+        }
+        this.factories.set(name, factory);
+    }
+
+    /**
+     * Resolves the requested service.
+     */
+    public resolve<T>(name: string): T {
+        if (this.services.has(name)) {
+            return this.services.get(name) as T;
+        }
+
+        if (this.factories.has(name)) {
+            const factory = this.factories.get(name) as FactoryFunction<T>;
+            const service = factory(this);
+            this.services.set(name, service); // Cache it as a singleton
+            this.factories.delete(name);
+            return service;
+        }
+
+        throw new ValidationError(`Dependency resolution failed: Service '${name}' not found in container.`);
+    }
+
+    /**
+     * Resets the container. Useful for test environments.
+     */
+    public reset(): void {
+        this.services.clear();
+        this.factories.clear();
+    }
+}
+
+export const container = ServiceContainer.getInstance();

package/src/shared/errors.ts

@@ -0,0 +1,72 @@
+/**
+ * Enterprise Base Error class for the Enderun Core Framework.
+ */
+export class EnderunBaseError extends Error {
+    public readonly code: string;
+    public readonly timestamp: Date;
+    public readonly details?: unknown;
+
+    constructor(message: string, code = "ENDERUN_INTERNAL_ERROR", details?: unknown) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.timestamp = new Date();
+        this.details = details;
+        
+        // Ensure proper prototype chain and capture stack trace
+        Object.setPrototypeOf(this, new.target.prototype);
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+
+    /**
+     * Converts the error into a structured JSON log format.
+     */
+    public toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            timestamp: this.timestamp.toISOString(),
+            details: this.details,
+            stack: this.stack,
+        };
+    }
+}
+
+/**
+ * Thrown when configuration loading or validation fails.
+ */
+export class ConfigurationError extends EnderunBaseError {
+    constructor(message: string, details?: unknown) {
+        super(message, "CONFIGURATION_ERROR", details);
+    }
+}
+
+/**
+ * Thrown when data schema or payload validation fails.
+ */
+export class ValidationError extends EnderunBaseError {
+    constructor(message: string, details?: unknown) {
+        super(message, "VALIDATION_ERROR", details);
+    }
+}
+
+/**
+ * Thrown when adapter initialization or execution fails.
+ */
+export class AdapterError extends EnderunBaseError {
+    constructor(message: string, adapterId: string, details?: unknown) {
+        super(`Adapter '${adapterId}' failure: ${message}`, "ADAPTER_ERROR", details);
+    }
+}
+
+/**
+ * Thrown when orchestration or agent communication fails.
+ */
+export class OrchestrationError extends EnderunBaseError {
+    constructor(message: string, details?: unknown) {
+        super(message, "ORCHESTRATION_ERROR", details);
+    }
+}

package/src/shared/logger.ts

@@ -0,0 +1,139 @@
+import chalk from "chalk";
+import fs from "fs";
+import path from "path";
+
+export enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    FATAL = 4,
+}
+
+export interface LoggerConfig {
+    minLevel: LogLevel;
+    enableColors: boolean;
+    jsonFormat: boolean;
+    logFile?: string;
+}
+
+export class EnterpriseLogger {
+    private config: LoggerConfig;
+    private static instance: EnterpriseLogger;
+
+    private constructor() {
+        const isProd = process.env.NODE_ENV === "production";
+        this.config = {
+            minLevel: isProd ? LogLevel.INFO : LogLevel.DEBUG,
+            enableColors: !isProd,
+            jsonFormat: isProd,
+        };
+    }
+
+    public static getInstance(): EnterpriseLogger {
+        if (!EnterpriseLogger.instance) {
+            EnterpriseLogger.instance = new EnterpriseLogger();
+        }
+        return EnterpriseLogger.instance;
+    }
+
+    public configure(config: Partial<LoggerConfig>): void {
+        this.config = { ...this.config, ...config };
+        
+        if (this.config.logFile) {
+            try {
+                const dir = path.dirname(this.config.logFile);
+                if (!fs.existsSync(dir)) {
+                    fs.mkdirSync(dir, { recursive: true });
+                }
+            } catch (err) {
+                console.error(`[Logger] Failed to create log directory: ${err}`);
+            }
+        }
+    }
+
+    private formatMessage(level: LogLevel, message: string, meta?: unknown): string {
+        const timestamp = new Date().toISOString();
+        const pid = process.pid;
+
+        if (this.config.jsonFormat) {
+            return JSON.stringify({
+                timestamp,
+                level: LogLevel[level],
+                pid,
+                message,
+                meta,
+            });
+        }
+
+        const levelName = LogLevel[level].padEnd(5);
+        let coloredLevel = levelName;
+
+        if (this.config.enableColors) {
+            switch (level) {
+                case LogLevel.DEBUG:
+                    coloredLevel = chalk.blue(levelName);
+                    break;
+                case LogLevel.INFO:
+                    coloredLevel = chalk.green(levelName);
+                    break;
+                case LogLevel.WARN:
+                    coloredLevel = chalk.yellow(levelName);
+                    break;
+                case LogLevel.ERROR:
+                    coloredLevel = chalk.red(levelName);
+                    break;
+                case LogLevel.FATAL:
+                    coloredLevel = chalk.bgRed.white.bold(levelName);
+                    break;
+            }
+        }
+
+        const metaStr = meta ? ` | Meta: ${JSON.stringify(meta)}` : "";
+        return `[${timestamp}] [PID:${pid}] [${coloredLevel}]: ${message}${metaStr}`;
+    }
+
+    private log(level: LogLevel, message: string, meta?: unknown): void {
+        if (level < this.config.minLevel) return;
+
+        const formatted = this.formatMessage(level, message, meta);
+
+        // Output to console
+        if (level >= LogLevel.ERROR) {
+            console.error(formatted);
+        } else {
+            console.log(formatted);
+        }
+
+        // Output to file if configured
+        if (this.config.logFile) {
+            try {
+                fs.appendFileSync(this.config.logFile, formatted + "\n", "utf8");
+            } catch (err) {
+                console.error(`[Logger] Failed to write to log file: ${err}`);
+            }
+        }
+    }
+
+    public debug(message: string, meta?: unknown): void {
+        this.log(LogLevel.DEBUG, message, meta);
+    }
+
+    public info(message: string, meta?: unknown): void {
+        this.log(LogLevel.INFO, message, meta);
+    }
+
+    public warn(message: string, meta?: unknown): void {
+        this.log(LogLevel.WARN, message, meta);
+    }
+
+    public error(message: string, meta?: unknown): void {
+        this.log(LogLevel.ERROR, message, meta);
+    }
+
+    public fatal(message: string, meta?: unknown): void {
+        this.log(LogLevel.FATAL, message, meta);
+    }
+}
+
+export const logger = EnterpriseLogger.getInstance();

package/templates/architecture/agents-manifest.md

@@ -0,0 +1,79 @@
+# 🎖️ Agent Enderun — Agent Army Manifest
+
+This document serves as the complete manifest of the 13 specialist agents forming the **Enderun Army**. Each agent is mapped to a specific capability index, toolset, and specialized directive under the Enderun Discipline (Osmanlı Nizami).
+
+---
+
+## 🏛️ Agent Army Overview
+
+| Agent Name | Role | Capability | Primary Tools | Tags |
+| :--- | :--- | :--- | :--- | :--- |
+| **`@manager`** | Orchestration | 10/10 | `orchestrate_loop`, `send_agent_message` | `core`, `orchestration` |
+| **`@architect`** | System Design | 9/10 | `write_file`, `replace_text` | `core`, `design` |
+| **`@backend`** | Backend Logic | 9/10 | `replace_text`, `run_shell_command` | `core`, `logic` |
+| **`@frontend`** | User Interface | 9/10 | `replace_text`, `view_file` | `core`, `ui` |
+| **`@quality`** | Quality Audit | 9/10 | `run_shell_command`, `view_file` | `core`, `audit` |
+| **`@database`** | Data Management | 9/10 | `replace_text`, `run_shell_command` | `core`, `data` |
+| **`@devops`** | Infrastructure | 9/10 | `run_shell_command`, `view_file` | `core`, `infra` |
+| **`@explorer`** | Reconnaissance | 8/10 | `grep_search`, `list_dir`, `glob` | `core`, `recon` |
+| **`@git`** | Version Control | 9/10 | `run_shell_command`, `view_file` | `core`, `logistics` |
+| **`@mobile`** | Mobile Apps | 9/10 | `replace_text`, `view_file` | `core`, `mobile` |
+| **`@native`** | System-Level | 9/10 | `run_shell_command`, `replace_text` | `core`, `native` |
+| **`@security`** | Security Audit | 10/10 | `grep_search`, `run_shell_command` | `core`, `security` |
+| **`@analyst`** | Requirements | 9/10 | `grep_search`, `list_dir` | `core`, `strategy` |
+
+---
+
+## 🤖 Specialist Directives
+
+### 1. `@manager` (Orchestrator)
+- **Directive:** Strategic commander of the army. Coordinates executions, schedules traces, and delegates tasks to specialists.
+- **Mandate:** Enforces Enderun discipline, inherits and passes Trace IDs, and handles final compliance approvals.
+
+### 2. `@architect` (Lead Architect)
+- **Directive:** Outlines initial codebase design, defines schema contracts, and manages the architectural blueprint.
+- **Mandate:** Enforces strict modular boundaries and verifies structural sanity.
+
+### 3. `@backend` (Backend Specialist)
+- **Directive:** Builds REST/GraphQL API systems, develops server components, and manages server business rules.
+- **Mandate:** Ensures robust error handling, schema boundaries, and server logic.
+
+### 4. `@frontend` (Frontend Specialist)
+- **Directive:** Builds user interfaces, manages layouts and states using modern styling (Panda CSS, CSS variables).
+- **Mandate:** Enforces design systems, accessibility, and high performance rendering.
+
+### 5. `@quality` (Quality Specialist)
+- **Directive:** Validates unit coverage, performs static analyses, and ensures code rules compliance.
+- **Mandate:** Runs ESLint rules, checks console logs, and audits project safety.
+
+### 6. `@database` (Database Specialist)
+- **Directive:** Designs relational/NoSQL schemas, writes migrations, and optimizes SQL query metrics.
+- **Mandate:** Guarantees data transaction integrity and index configurations.
+
+### 7. `@devops` (Infrastructure Specialist)
+- **Directive:** Establishes CI/CD pipelines, configures Docker environments, and tracks cloud deployments.
+- **Mandate:** Ensures high availability, automation scripts, and safe release cycles.
+
+### 8. `@explorer` (Intel Explorer)
+- **Directive:** Gathers codebase intelligence, discovers file dependencies, and maps codebase symbols.
+- **Mandate:** Guides planning agents by providing context graphs and code dependencies.
+
+### 9. `@git` (Logistics Master)
+- **Directive:** Handles atomic commit flows, merges code, resolves conflicts, and manages release tags.
+- **Mandate:** Enforces descriptive commit tags mapped to active Trace IDs.
+
+### 10. `@mobile` (Mobile Specialist)
+- **Directive:** Implements mobile interfaces using cross-platform layouts (React Native / Expo).
+- **Mandate:** Optimizes mobile assets, native performance, and state stores.
+
+### 11. `@native` (Native Division)
+- **Directive:** Interfaces with native operating system hooks, constructs desktop platforms, and manages hardware bridges.
+- **Mandate:** Exercises deep security protocols during system interactions.
+
+### 12. `@security` (Security Specialist)
+- **Directive:** Audits repositories for credentials/secrets, evaluates package dependencies, and verifies authentication flows.
+- **Mandate:** Rejects insecure actions, validates cryptographic keys, and enforces access control checks.
+
+### 13. `@analyst` (Business Analyst)
+- **Directive:** Maps requirements to codebase implementations, writes business specification rules, and audits contracts.
+- **Mandate:** Validates feature alignment against system specifications.

package/templates/architecture/enterprise-architecture.md

@@ -0,0 +1,69 @@
+# 🎖️ Agent Enderun — Enterprise Architecture & Standards
+
+This document establishes the architecture patterns, design guidelines, and code structures of the **Enderun Core Framework** for enterprise deployments.
+
+---
+
+## 🏛️ Project Directory Structure
+
+```text
+agent-enderun/
+├── bin/                       # Executable CLI entrypoints
+├── docs/                      # Technical documentation & design guides
+├── framework-mcp/             # Modular MCP server implementation (workspace)
+│   ├── src/                   # MCP server source files
+│   └── tests/                 # Unit tests for MCP server tools
+├── src/                       # CLI & Core framework logic
+│   ├── cli/                   # Command line interface commands & adapters
+│   │   ├── adapters/          # Target-specific IDE adapters (VS Code, Cursor, etc.)
+│   │   ├── commands/          # Subcommand handlers (init, status, check)
+│   │   └── utils/             # CLI-specific utilities
+│   ├── modules/               # Core framework modules
+│   │   ├── adapters/          # Target environment adapter profiles
+│   │   ├── agents/            # Orchestrator & Specialist Agent definitions
+│   │   └── skills/            # Capability templates for specialist actions
+│   └── shared/                # Core shared business components
+│       ├── config.ts          # Zod environment configuration
+│       ├── container.ts       # Dependency injection container
+│       ├── errors.ts          # Standard typed domain errors
+│       ├── fs.ts              # File system helper wrappers
+│       └── logger.ts          # Enterprise logging subsystem
+```
+
+---
+
+## ⚙️ Core Design Principles
+
+### 1. Unified Domain Errors
+All errors thrown by modules must inherit from `EnderunBaseError` in [src/shared/errors.ts](file:///Users/ybekar/Desktop/Projeler/agent-enderun/src/shared/errors.ts).
+This ensures:
+- Unique error codes (`CONFIGURATION_ERROR`, `VALIDATION_ERROR`, etc.)
+- Metadata enrichment via the `details` field
+- Structured JSON serialization in production environments
+
+### 2. Zod-Validated Environments
+Configuration options must never be read directly from raw environment variables (`process.env`). Instead, they are parsed and frozen inside [src/shared/config.ts](file:///Users/ybekar/Desktop/Projeler/agent-enderun/src/shared/config.ts) at initialization. If a required value is missing, the application crashes immediately with a clean explanation.
+
+### 3. Service Container (Dependency Injection)
+To write testable and decoupled code, singletons and factories are registered and resolved using the `ServiceContainer` defined in [src/shared/container.ts](file:///Users/ybekar/Desktop/Projeler/agent-enderun/src/shared/container.ts).
+```typescript
+import { container } from "./shared/container.js";
+
+// Register
+container.register("Logger", logger);
+
+// Resolve
+const logger = container.resolve<EnterpriseLogger>("Logger");
+```
+
+### 4. Structured Observability
+Use `EnterpriseLogger` in [src/shared/logger.ts](file:///Users/ybekar/Desktop/Projeler/agent-enderun/src/shared/logger.ts) for logging:
+- In **development**, logs are colorized and formatted for human readability.
+- In **production**, logs are structured as JSON for log aggregators (e.g. Datadog, ELK).
+
+---
+
+## 🛡️ Code & Type Guidelines
+- **Strict Typing:** Always keep `"strict": true` in `tsconfig.json`. Explicit return types are required on all exports.
+- **Asynchronous Flow:** Use async/await over raw promise chains. Handle failures with localized try/catch blocks and wrap in domain errors.
+- **Atomic Operations:** Always use transactional or surgical replacements when editing configuration/code files.

package/templates/architecture/standards/crud-governance.md

@@ -0,0 +1,46 @@
+# Enterprise CRUD & Admin Governance Protocol (v1.0.0)
+
+This protocol defines the strict operational boundaries, coding practices, and routing rules for High-Risk CRUD (Create, Read, Update, Delete) operations and Administrative actions within Agent Enderun projects.
+
+---
+
+## 🔒 1. High-Risk Action Classification
+
+To maintain security, database consistency, and prevent unauthorized system changes, actions are split into **Standard Operations** and **High-Risk Operations**.
+
+### 🛑 High-Risk Administrative Operations (Requires @manager Sign-Off)
+The following actions must **never** be performed by specialist agents (`@backend`, `@frontend`, `@database`, etc.) autonomously. They must halt execution and redirect the task to `@manager` via the Hermes Message Broker.
+
+1. **User & Permission Management:** Modifying roles, assigning admin rights, creating api keys.
+2. **Bulk Destructive Operations:** Truncating tables, purging databases, executing mass-deletions without strict tenant-isolation clauses.
+3. **Database Schema Alterations:** Running database migrations, altering column constraints, deleting tables.
+4. **PII & Data Export:** Bulk exporting personal user info, system settings, or database backups.
+5. **System Config & CSP Policies:** Modifying environment variables, CORS origins, or content security policies.
+6. **Billing & Financial Actions:** Integrating payment gateways, editing subscription rules.
+
+---
+
+## 🛡️ 2. Specialist Redirection Policy
+
+When a specialist agent receives a request containing any High-Risk Administrative Operation, it must immediately return the following standard refusal message and halt code output:
+
+> **[REFUSAL - Corporate CRUD Governance Standard]**
+> I am not authorized to perform administrative actions or bulk mutations. 
+> I have redirected this request to the Orchestrator (@manager) under Trace ID: {{TRACE_ID}}.
+> Please execute the manager approval sequence to proceed.
+
+### Action Flow:
+1. **Detect** high-risk keyword or context in the task.
+2. **Create** an approval request using the `send_agent_message` tool targeting `@manager` with category `ALERT` and priority `HIGH`.
+3. **Update** state in `STATUS.md` to `WAITING` with note `BLOCKED_BY_CRUD_GOVERNANCE`.
+
+---
+
+## 🧬 3. Safe Coding Standard (Read/Write Rules)
+
+For permitted Standard CRUD operations, the following rules are strictly enforced:
+
+1. **Isolated Repository Pattern:** All database reads and writes must be encapsulated in repository/service classes. Writing database queries directly inside fastify controllers or nextjs actions is **strictly forbidden**.
+2. **No Raw SQL:** All database mutations must use typed query builders (e.g. `Kysely`). Direct string-concatenated SQL queries are **strictly forbidden** to prevent SQL injection.
+3. **Branded Types:** Entities must use branded types (e.g. `UserId`, `ProjectId`) instead of primitive types (`string`, `number`) to avoid type mixing.
+4. **Soft Deletes by Default:** All business-domain deletions must use a `deletedAt` timestamp instead of raw SQL `DELETE` mutations, unless explicitly designated by `@manager`.

package/templates/architecture/standards/data-fetching-patterns.md

@@ -0,0 +1,13 @@
+# Architecture Patterns & Data Fetching
+
+## 1. UI Layout & Component Structure
+- **Shared UI:** All atomic components (Button, Input, etc.) must be created in `apps/web/src/components/ui/` using **Panda CSS**.
+- **Layouts:** Use wrapper layouts (`Shell`, `Workspace`) in `apps/web/src/components/layout/`. Every page must utilize these layouts to maintain consistency.
+- **Procedural Continuity:** Never re-create an existing component. Search the `components/ui/` directory first.
+
+## 2. Data Fetching & API (CRUD) Patterns
+- **Repository Pattern:** Backend logic must be separated into service/repository layers. No direct DB calls in controllers.
+- **Contract-First:** All API endpoints must use types imported from `apps/backend/src/types/`.
+- **API Layer:** Frontend must use typed fetcher functions located in `apps/web/src/api/`.
+- **Validation:** Use `zod` for request validation on the backend and response validation on the frontend.
+- **Audit Logging:** Every mutation (POST/PUT/PATCH/DELETE) MUST trigger an audit log service call with the current Trace ID.

package/templates/architecture/standards/design-system.md

@@ -0,0 +1,31 @@
+# Design System — Agent Enderun (Enterprise)
+
+## 1. Design Philosophy
+The Agent Enderun Design System focuses on **"Enterprise Clarity"**. Our interfaces are professional, minimalist tools designed to maximize data comprehension and operational speed. 
+
+- **Clarity:** Every pixel must serve a purpose. If it doesn't aid understanding or action, remove it.
+- **Consistency:** Uniform visual language across all applications.
+- **Responsiveness:** Fluid adaptation to any screen size, from mobile to ultra-wide monitors.
+
+## 2. Technical Requirements
+- **Styling:** Panda CSS is MANDATORY. Tailwind, CSS-in-JS, and raw CSS modules are FORBIDDEN.
+- **Zero UI Library:** No external components (MUI, AntD, Shadcn). All UI components must be built from scratch in `apps/web/src/components/ui/`.
+- **Tokenization:** All values (colors, spacing, typography) MUST use `panda.config.ts` tokens. NO hardcoded pixels.
+- **Responsiveness:** Mobile-First design is MANDATORY.
+
+## 3. Responsive Mandate (Mobile-First)
+- **Design Strategy:** Design for 320px width first.
+- **Breakpoints:**
+  - `sm`: 640px
+  - `md`: 768px
+  - `lg`: 1024px
+  - `xl`: 1280px
+  - `2xl`: 1536px
+- **Layouts:** Use Flexbox and Grid. Fixed widths are FORBIDDEN. Use `clamp()` for fluid typography and spacing where applicable.
+- **Reflow:** Content MUST gracefully wrap, stack, or collapse based on screen width without horizontal scrollbars.
+
+## 4. UI/UX Interaction Standards
+- **Interactions:** Hover, Active, and Disabled states are MANDATORY for all interactive elements.
+- **Feedback:** Async operations MUST show Loading states and Toast notifications on completion/error.
+- **Blocking Dialogues:** Native `alert()` and `confirm()` functions are **FORBIDDEN**. Use project-integrated `Modal` components for blocking user interactions and `Toaster` for non-blocking feedback.
+- **Focus:** All interactive elements must have a visible `focus` state for accessibility.

package/templates/architecture/standards/documentation-ownership.md

@@ -0,0 +1,21 @@
+# 🎖️ Agent Enderun — Documentation Ownership & Memory Protocol
+
+This document establishes the binding discipline for where project documentation is stored and how AI agents interact with it.
+
+## 🏛️ Core Principles
+
+1. **Human-AI Separation of Concerns:**
+   - **`docs/` (Root Directory):** Single Source of Truth (SSOT) for human intentions, business requirements, API specifications, and architectural standards.
+   - **`.gemini/` or `.agents/` (Framework Directory):** Operational workspace and memory of the AI agents. Contains state machines, task tracking, rules, and internal logs.
+
+2. **The Documentation Discipline:**
+   - The user clarifies requirements in the chat.
+   - Once requirements are finalized, they are documented in the root `docs/` directory (e.g., `docs/project-docs.md`, `docs/api/`, etc.) by the user or the agent.
+   - When building features or validating code, the agent **reads** the documents from `docs/` and uses them as the blueprint.
+   - The agent **must not** duplicate requirements inside the internal memory (`PROJECT_MEMORY.md`). The internal memory only tracks *what has been done* and *what is currently running* (Trace ID, active phase, history of implemented steps referencing the doc files).
+
+## 🛡️ Agent Rules
+
+- **Do Not Pollute Internal Memory:** Never copy full requirement specifications or code files into `.gemini/memory/PROJECT_MEMORY.md`. Refer to the root `docs/` files instead.
+- **Exclusivity:** All project-specific architectural records, API catalogs, database schemas, and user manuals must be created in the `docs/` folder.
+- **Read Before Code:** Before writing any application code or generating files, the agent must check the root `docs/` directory for context and specifications.

package/templates/architecture/standards/logging.md

@@ -0,0 +1,7 @@
+# Logging & Audit Standard
+
+- **No Console.log:** Production code MUST NOT use `console.log`, `console.warn`, or `console.error`. These are FORBIDDEN in the codebase.
+- **Structured Logging:** All logging MUST go through the centralized `Logger` service (`apps/backend/src/services/logger.ts`). Logs must be produced in JSON format.
+- **Traceability:** Every log entry MUST include the active `traceId` context to ensure cross-agent and cross-service traceability.
+- **Audit Logging:** Every state-mutating operation (POST, PUT, PATCH, DELETE) MUST trigger an `AuditService.log()` call, linking the action to the responsible agent, Trace ID, and entity ID.
+- **Log Persistence:** Logs must be persisted in an structured manner suitable for downstream ingestion by log management systems.

package/templates/architecture/standards/mobile-standards.md

@@ -0,0 +1,48 @@
+# Mobile Standards — Agent Enderun (React Native & Expo)
+
+This document establishes the responsive styling, safe layout, and development standards for mobile applications.
+
+## 📱 1. Safe Layout & Notches
+
+- **SafeAreaView Usage:** All screen entry points must be wrapped in a `SafeAreaView` (from `react-native-safe-area-context`) to avoid overlap with device notches, status bars, and home indicators.
+- **Avoid Hardcoded Padding/Margins:** Use the dynamic insets returned by the `useSafeAreaInsets()` hook for custom spacing.
+
+## 📏 2. Fluid & Responsive Dimensions
+
+- **No Hardcoded Absolute Sizes:** Hardcoding absolute widths and heights (e.g. `width: 375`) is strictly forbidden. 
+- **Flexbox First:** Build layouts using Flexbox (`flex: 1`, `flexDirection`, `justifyContent`, `alignItems`).
+- **Dynamic Scales:** Use percentages (`width: "100%"`) or calculate dynamic values using `useWindowDimensions()` or a scaling utility:
+  ```typescript
+  import { Dimensions } from "react-native";
+  const { width, height } = Dimensions.get("window");
+  
+  // Base design width (e.g., iPhone 14 / 390px wide)
+  const scale = width / 390;
+  export const normalize = (size: number) => Math.round(size * scale);
+  ```
+
+## 🎨 3. Typography & Styling
+
+- **System Fonts:** Use native platform fonts or custom configured Expo fonts consistently.
+- **Fluid Typography:** Scale font sizes dynamically using scaling utilities so they look proportionate on both compact screens and tablets.
+- **Platform Selection:** Target Android and iOS specifically when styling differs (e.g., shadows vs elevation) using `Platform.select()`:
+  ```typescript
+  const cardStyle = {
+    ...Platform.select({
+      ios: {
+        shadowColor: "#000",
+        shadowOffset: { width: 0, height: 2 },
+        shadowOpacity: 0.1,
+        shadowRadius: 4,
+      },
+      android: {
+        elevation: 4,
+      },
+    }),
+  };
+  ```
+
+## 📦 4. Asset & Network Optimization
+
+- **Vector Graphics:** Prefer SVG files over high-resolution PNG/JPG files for icons and illustrations to prevent scaling pixelation.
+- **Image Performance:** Always use caching and optimizing components like Expo's `Image` with appropriate content-fit modes.

package/templates/architecture/standards/tech-stack.md

@@ -0,0 +1,9 @@
+# Tech Stack — Agent Enderun (Enterprise)
+
+- **Execution Profile:** Full (Enterprise)
+- **Frontend:** React (Vite), Panda CSS (Zero UI Library)
+- **Backend:** Fastify API, Kysely (Query Builder)
+- **Database:** PostgreSQL
+- **Testing:** Vitest (Integration + Unit)
+- **Auth:** Contract-first (Type definitions)
+- **Versioning:** API-path versioning (/api/v1/...)