agent-enderun 1.1.3 → 1.1.5

package/src/cli/utils/app.ts

@@ -1,7 +1,6 @@
 import fs from "fs";
 import path from "path";
-import crypto from "crypto";
-import { ensureDir, writeTextFile, writeJsonFile } from "../utils/fs.js";
+import { ensureDir, writeTextFile, writeJsonFile, computeTypesHash } from "../utils/fs.js";
 import { updateProjectMemory } from "./memory.js"; 
 import { slugifyName, titleCase } from "../utils/string.js";
 import { getConfiguredPaths, getMemoryPath } from "./memory.js";
@@ -86,20 +85,10 @@ export function updateContractHashFile() {
     const contractPath = path.join(targetDir, pathsMap.backend, "contract.version.json");
     if (!fs.existsSync(sharedDir) || !fs.existsSync(contractPath)) return;
 
-    const walk = (dir: string): string[] => fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
-        const fullPath = path.join(dir, entry.name);
-        return entry.isDirectory() ? walk(fullPath) : (entry.name.endsWith(".ts") ? [fullPath] : []);
-    });
-    const hash = crypto.createHash("sha256");
-    for (const filePath of walk(sharedDir).sort()) {
-        hash.update(path.relative(targetDir, filePath));
-        hash.update("\0");
-        hash.update(fs.readFileSync(filePath));
-        hash.update("\0");
-    }
+    const currentHash = computeTypesHash(targetDir, sharedDir);
 
     const contract = JSON.parse(fs.readFileSync(contractPath, "utf8"));
-    contract.contract_hash = hash.digest("hex");
+    contract.contract_hash = currentHash;
     contract.last_updated = new Date().toISOString();
     fs.writeFileSync(contractPath, JSON.stringify(contract, null, 2));
 }
@@ -339,36 +328,111 @@ export function createBackendFiles(spec: AppSpec) {
         include: ["src/**/*.ts"],
     });
 
-    writeTextFile(path.join(targetDir, backendDir, "src/data.ts"), [
-        "import type { Customer, DashboardSummary, ReportMetric, Role, User } from \"./types/index.js\";",
+    const srcDir = path.join(targetDir, backendDir, "src");
+    ensureDir(path.join(srcDir, "database"));
+    ensureDir(path.join(srcDir, "repositories"));
+    ensureDir(path.join(srcDir, "services"));
+
+    writeTextFile(path.join(srcDir, "database/memoryDb.ts"), [
+        "import type { Customer, ReportMetric, Role, User } from \"../types/index.js\";",
         "",
         "const now = new Date().toISOString();",
         "",
-        "export const roles: Role[] = [",
+        "export const rolesDb: Role[] = [",
         "  { id: \"role_admin\" as Role[\"id\"], name: \"Admin\", permissions: [\"users:manage\", \"reports:view\", \"customers:manage\"] },",
         "  { id: \"role_manager\" as Role[\"id\"], name: \"Manager\", permissions: [\"reports:view\", \"customers:manage\"] },",
         "  { id: \"role_viewer\" as Role[\"id\"], name: \"Viewer\", permissions: [\"reports:view\"] },",
         "];",
         "",
-        "export const users: User[] = [",
-        "  { id: \"user_1\" as User[\"id\"], email: \"admin@example.com\", fullName: \"Admin User\", role: \"ADMIN\", createdAt: now },",
-        "  { id: \"user_2\" as User[\"id\"], email: \"manager@example.com\", fullName: \"Sales Manager\", role: \"DEVELOPER\", createdAt: now },",
+        "export const usersDb: User[] = [",
+        "  { id: \"user_1\" as User[\"id\"], email: \"admin@example.com\", fullName: \"Admin User\", role: \"ADMIN\", createdAt: now, updatedAt: now },",
+        "  { id: \"user_2\" as User[\"id\"], email: \"manager@example.com\", fullName: \"Sales Manager\", role: \"DEVELOPER\", createdAt: now, updatedAt: now },",
         "];",
         "",
-        "export const customers: Customer[] = [",
-        "  { id: \"customer_1\" as Customer[\"id\"], name: \"Northwind\", ownerId: users[1].id, status: \"ACTIVE\", annualValue: 125000, createdAt: now },",
-        "  { id: \"customer_2\" as Customer[\"id\"], name: \"Acme Corp\", ownerId: users[1].id, status: \"LEAD\", annualValue: 82000, createdAt: now },",
-        "  { id: \"customer_3\" as Customer[\"id\"], name: \"Globex\", ownerId: users[0].id, status: \"AT_RISK\", annualValue: 54000, createdAt: now },",
+        "export const customersDb: Customer[] = [",
+        "  { id: \"customer_1\" as Customer[\"id\"], name: \"Northwind\", ownerId: usersDb[1].id, status: \"ACTIVE\", annualValue: 125000, createdAt: now, updatedAt: now },",
+        "  { id: \"customer_2\" as Customer[\"id\"], name: \"Acme Corp\", ownerId: usersDb[1].id, status: \"LEAD\", annualValue: 82000, createdAt: now, updatedAt: now },",
+        "  { id: \"customer_3\" as Customer[\"id\"], name: \"Globex\", ownerId: usersDb[0].id, status: \"AT_RISK\", annualValue: 54000, createdAt: now, updatedAt: now },",
         "];",
         "",
-        "export const reports: ReportMetric[] = [",
+        "export const reportsDb: ReportMetric[] = [",
         "  { id: \"report_pipeline\" as ReportMetric[\"id\"], label: \"Pipeline\", value: 261000, trend: \"UP\" },",
         "  { id: \"report_active_customers\" as ReportMetric[\"id\"], label: \"Active Customers\", value: 1, trend: \"FLAT\" },",
         "  { id: \"report_risk\" as ReportMetric[\"id\"], label: \"At Risk\", value: 1, trend: \"DOWN\" },",
         "];",
+    ].join("\n"));
+
+    writeTextFile(path.join(srcDir, "repositories/user.repository.ts"), [
+        "import { usersDb } from \"../database/memoryDb.js\";",
+        "import type { User } from \"../types/index.js\";",
         "",
-        "export function getDashboardSummary(): DashboardSummary {",
-        "  return { customers, users, roles, reports };",
+        "export class UserRepository {",
+        "  async findAll(): Promise<User[]> {",
+        "    return usersDb.filter(u => !u.deletedAt);",
+        "  }",
+        "",
+        "  async findByEmail(email: string): Promise<User | null> {",
+        "    return usersDb.find(u => u.email === email && !u.deletedAt) || null;",
+        "  }",
+        "}",
+    ].join("\n"));
+
+    writeTextFile(path.join(srcDir, "repositories/customer.repository.ts"), [
+        "import { customersDb } from \"../database/memoryDb.js\";",
+        "import type { Customer } from \"../types/index.js\";",
+        "",
+        "export class CustomerRepository {",
+        "  async findAll(): Promise<Customer[]> {",
+        "    return customersDb.filter(c => !c.deletedAt);",
+        "  }",
+        "}",
+    ].join("\n"));
+
+    writeTextFile(path.join(srcDir, "repositories/role.repository.ts"), [
+        "import { rolesDb } from \"../database/memoryDb.js\";",
+        "import type { Role } from \"../types/index.js\";",
+        "",
+        "export class RoleRepository {",
+        "  async findAll(): Promise<Role[]> {",
+        "    return rolesDb;",
+        "  }",
+        "}",
+    ].join("\n"));
+
+    writeTextFile(path.join(srcDir, "repositories/report.repository.ts"), [
+        "import { reportsDb } from \"../database/memoryDb.js\";",
+        "import type { ReportMetric } from \"../types/index.js\";",
+        "",
+        "export class ReportRepository {",
+        "  async findAll(): Promise<ReportMetric[]> {",
+        "    return reportsDb;",
+        "  }",
+        "}",
+    ].join("\n"));
+
+    writeTextFile(path.join(srcDir, "services/dashboard.service.ts"), [
+        "import { UserRepository } from \"../repositories/user.repository.js\";",
+        "import { CustomerRepository } from \"../repositories/customer.repository.js\";",
+        "import { RoleRepository } from \"../repositories/role.repository.js\";",
+        "import { ReportRepository } from \"../repositories/report.repository.js\";",
+        "import type { DashboardSummary } from \"../types/index.js\";",
+        "",
+        "export class DashboardService {",
+        "  private userRepo = new UserRepository();",
+        "  private customerRepo = new CustomerRepository();",
+        "  private roleRepo = new RoleRepository();",
+        "  private reportRepo = new ReportRepository();",
+        "",
+        "  async getSummary(): Promise<DashboardSummary> {",
+        "    const [users, customers, roles, reports] = await Promise.all([",
+        "      this.userRepo.findAll(),",
+        "      this.customerRepo.findAll(),",
+        "      this.roleRepo.findAll(),",
+        "      this.reportRepo.findAll(),",
+        "    ]);",
+        "",
+        "    return { users, customers, roles, reports };",
+        "  }",
         "}",
     ].join("\n"));
 
@@ -376,22 +440,45 @@ export function createBackendFiles(spec: AppSpec) {
         "import Fastify from \"fastify\";",
         "import cors from \"@fastify/cors\";",
         "import { z } from \"zod\";",
-        "import { customers, getDashboardSummary, reports, roles, users } from \"./data.js\";",
+        "import { UserRepository } from \"./repositories/user.repository.js\";",
+        "import { CustomerRepository } from \"./repositories/customer.repository.js\";",
+        "import { RoleRepository } from \"./repositories/role.repository.js\";",
+        "import { ReportRepository } from \"./repositories/report.repository.js\";",
+        "import { DashboardService } from \"./services/dashboard.service.js\";",
         "",
         "const app = Fastify({ logger: true });",
         "await app.register(cors, { origin: true });",
         "",
+        "const userRepo = new UserRepository();",
+        "const customerRepo = new CustomerRepository();",
+        "const roleRepo = new RoleRepository();",
+        "const reportRepo = new ReportRepository();",
+        "const dashboardService = new DashboardService();",
+        "",
         "app.get(\"/health\", async () => ({ ok: true, service: \"agent-enderun-backend\" }));",
-        "app.get(\"/api/v1/dashboard\", async () => ({ data: getDashboardSummary() }));",
-        "app.get(\"/api/v1/users\", async () => ({ data: users }));",
-        "app.get(\"/api/v1/roles\", async () => ({ data: roles }));",
-        "app.get(\"/api/v1/customers\", async () => ({ data: customers }));",
+        "app.get(\"/api/v1/dashboard\", async () => {",
+        "  const summary = await dashboardService.getSummary();",
+        "  return { data: summary };",
+        "});",
+        "app.get(\"/api/v1/users\", async () => {",
+        "  const users = await userRepo.findAll();",
+        "  return { data: users };",
+        "});",
+        "app.get(\"/api/v1/roles\", async () => {",
+        "  const roles = await roleRepo.findAll();",
+        "  return { data: roles };",
+        "});",
+        "app.get(\"/api/v1/customers\", async () => {",
+        "  const customers = await customerRepo.findAll();",
+        "  return { data: customers };",
+        "});",
         "app.get(\"/api/v1/reports\", async (request, reply) => {",
         "  interface QueryParams {",
         "    page?: number;",
         "    limit?: number;",
         "  }",
         "  const { page = 1, limit = 10 } = request.query as QueryParams;",
+        "  const reports = await reportRepo.findAll();",
         "  const startIndex = (Number(page) - 1) * Number(limit);",
         "  const endIndex = startIndex + Number(limit);",
         "  const paginatedReports = reports.slice(startIndex, endIndex);",
@@ -409,7 +496,11 @@ export function createBackendFiles(spec: AppSpec) {
         "  const body = z.object({ email: z.string().email(), password: z.string().min(1) }).safeParse(request.body);",
         "  if (!body.success) return reply.code(400).send({ error: { code: \"VALIDATION_ERROR\", message: \"Invalid login payload\" } });",
         "",
-        "  const user = users.find((item) => item.email === body.data.email) || users[0];",
+        "  const user = await userRepo.findByEmail(body.data.email);",
+        "  if (!user) {",
+        "    const allUsers = await userRepo.findAll();",
+        "    return { data: { user: allUsers[0], token: \"demo-token\", expiresAt: new Date(Date.now() + 3600000).toISOString() } };",
+        "  }",
         "  return { data: { user, token: \"demo-token\", expiresAt: new Date(Date.now() + 3600000).toISOString() } };",
         "});",
         "",

package/src/cli/utils/fs.ts

@@ -1,5 +1,6 @@
 import fs from "fs";
 import path from "path";
+import crypto from "crypto";
 
 import { remapFrameworkContent } from "../adapters.js"; // Import from the new adapters.js
 import type { AdapterId } from "../adapters.js";
@@ -156,3 +157,19 @@ export function collectFiles(dir: string, extensions: string[]): string[] {
     });
     return results;
 }
+
+export function computeTypesHash(projectRoot: string, sharedDir: string): string {
+    const walk = (d: string): string[] => fs.readdirSync(d, { withFileTypes: true }).flatMap((e) => {
+        const fullPath = path.join(d, e.name);
+        return e.isDirectory() ? walk(fullPath) : (e.name.endsWith(".ts") ? [fullPath] : []);
+    });
+
+    const hash = crypto.createHash("sha256");
+    for (const filePath of walk(sharedDir).sort()) {
+        hash.update(path.relative(projectRoot, filePath));
+        hash.update("\0");
+        hash.update(fs.readFileSync(filePath));
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}

package/src/cli/utils/memory.ts

@@ -24,7 +24,10 @@ function findFrameworkDir(basePath: string): string | null {
     for (const dir of FRAMEWORK_DIR_CANDIDATES) {
         const dirPath = path.join(basePath, dir);
         if (fs.existsSync(dirPath) && fs.lstatSync(dirPath).isDirectory()) {
-            return dirPath;
+            const hasMemory = fs.existsSync(path.join(dirPath, "PROJECT_MEMORY.md")) ||
+                              fs.existsSync(path.join(dirPath, "memory/PROJECT_MEMORY.md")) ||
+                              fs.existsSync(path.join(dirPath, "config.json"));
+            if (hasMemory) return dirPath;
         }
     }
     return null;
@@ -121,6 +124,13 @@ export function initializeMemory(memoryPath: string, targetBase: string, dryRun
     if (!fs.existsSync(parentDir)) fs.mkdirSync(parentDir, { recursive: true });
     fs.writeFileSync(memoryPath, template);
     console.warn("✅ PROJECT_MEMORY.md initialized.");
+
+    const decisionsPath = path.join(parentDir, "DECISIONS.md");
+    if (!fs.existsSync(decisionsPath)) {
+        const decisionsTemplate = "# 🏛️ Architectural Decisions Log (ADR)\n\nThis file contains the fixed architectural choices and constraints for this project.\n\n## Decided Constraints\n- **Framework Integration:** Agent Enderun is the primary governance and orchestration layer.\n- **Language & Runtime:** TypeScript on Node.js.\n- **Package Manager:** npm.\n- **Monorepo Structure:** Monorepo using npm workspaces.\n- **Styling:** Panda CSS.\n";
+        fs.writeFileSync(decisionsPath, decisionsTemplate);
+        console.warn("✅ DECISIONS.md initialized.");
+    }
 }
 
 export function updateProjectMemory(section: string, content: string) {

package/src/modules/agents/definitions.ts

@@ -20,7 +20,7 @@ export const ALL_AGENTS: AgentDefinition[] = [
         tags: ["core", "orchestration"],
         stateMachine: "../schema/agent-lifecycle-schema.json",
         tools: ["orchestrate_loop", "send_agent_message", "view_file", "list_dir", "grep_search"],
-        instructions: "You represent the Enderun Discipline (Osmanlı Nizami). Your word is the law for the specialists. Delegate tasks with precision."
+        instructions: "You represent the Enderun Discipline (Osmanlı Nizami). Your word is the law for the specialists. Delegate tasks with precision using the send_agent_message tool. Enforce the Zero-Mock, Zero-UI-Library, and Branded Types policies strictly. Audit all specialist outputs and handle high-risk actions through the human-in-the-loop approval flow (managerApproval) via the approve command. Always sync active memory in PROJECT_MEMORY.md."
     },
     {
         name: "architect",
@@ -31,7 +31,7 @@ export const ALL_AGENTS: AgentDefinition[] = [
         tags: ["core", "design"],
         stateMachine: "../schema/agent-lifecycle-schema.json",
         tools: ["view_file", "write_file", "replace_text", "list_dir", "grep_search"],
-        instructions: "Design the project's foundation. Design must be flawless and adhere to the Nizam."
+        instructions: "Design the project's foundation. Design must be flawless and adhere to the Nizam. You possess the Control Plane Governance & Locking skill. Always prioritize reading rules and governance documents before designing contracts. Ensure type contract stability (contract.version.json), strictly forbid 'any' type, and enforce type safety across all boundaries."
     },
     {
         name: "backend",
@@ -42,7 +42,7 @@ export const ALL_AGENTS: AgentDefinition[] = [
         tags: ["core", "logic"],
         stateMachine: "../schema/agent-lifecycle-schema.json",
         tools: ["view_file", "replace_text", "run_shell_command", "list_dir", "grep_search"],
-        instructions: "Focus on server logic and databases. Any deviation from the Ferman is a breach of discipline."
+        instructions: "Focus on server logic and databases. Any deviation from the Ferman is a breach of discipline. You possess the Database Management & Migrations skill. Always prioritize reading rules and skills/database_management.md before writing API handlers or database code. Strictly enforce Branded Types for all IDs, use Kysely for queries (strictly forbid raw SQL strings), isolate queries in repository/service layers (forbid direct DB calls in controllers), and use robust try/catch blocks for error handling. You are strictly prohibited from performing High-Risk Administrative Operations (User/role management, bulk deletes, schema alterations, billing changes) autonomously. If requested, you must return a standard refusal, write a managerApproval request via send_agent_message to @manager, and shift to WAITING status."
     },
     {
         name: "frontend",
@@ -53,7 +53,7 @@ export const ALL_AGENTS: AgentDefinition[] = [
         tags: ["core", "ui"],
         stateMachine: "../schema/agent-lifecycle-schema.json",
         tools: ["view_file", "replace_text", "list_dir", "grep_search"],
-        instructions: "Build elegant and disciplined UIs with master craftsmanship."
+        instructions: "Build elegant, disciplined, and 100% responsive UIs. Always prioritize reading design standards and guidelines (like component-patterns.md) under docs/ or the framework's knowledge directory before starting any UI task. Enforce Mobile-First design, object-based responsive syntax ({ base: '...', md: '...' }), dynamic viewport units (dvh, dvw), and type-safe Panda CSS tokens. Never use external UI libraries. You are strictly prohibited from creating administrative UI elements (user/role management pages, billing pages, raw schema management tools) autonomously. Redirect such requests to @manager and request approval."
     },
     {
         name: "quality",
@@ -64,7 +64,7 @@ export const ALL_AGENTS: AgentDefinition[] = [
         tags: ["core", "audit"],
         stateMachine: "../schema/agent-lifecycle-schema.json",
         tools: ["run_shell_command", "view_file", "list_dir", "grep_search"],
-        instructions: "You are the inspector of the Nizam. Ensure every unit's work is perfect."
+        instructions: "You are the inspector of the Nizam. Ensure every unit's work is perfect. You possess the Quality Assurance & Testing skill. Always prioritize reading skills/quality_assurance.md (or equivalent inside the framework's skills directory) before performing audits, running linting, or checking coverage."
     },
     {
         name: "database",
@@ -75,7 +75,7 @@ export const ALL_AGENTS: AgentDefinition[] = [
         tags: ["core", "data"],
         stateMachine: "../schema/agent-lifecycle-schema.json",
         tools: ["view_file", "replace_text", "run_shell_command", "list_dir"],
-        instructions: "Manage data as the empire's treasury. Secure and optimized."
+        instructions: "Manage data as the empire's treasury. Secure and optimized. You possess the Database Management & Migrations skill. Always prioritize reading skills/database_management.md (or equivalent inside the framework's skills directory) before modifying databases, designing schemas, or creating migrations."
     },
     {
         name: "devops",
@@ -86,7 +86,7 @@ export const ALL_AGENTS: AgentDefinition[] = [
         tags: ["core", "infra"],
         stateMachine: "../schema/agent-lifecycle-schema.json",
         tools: ["run_shell_command", "view_file", "list_dir"],
-        instructions: "Maintain reliable supply lines and systems like fortresses."
+        instructions: "Maintain reliable supply lines and systems like fortresses. You possess the DevOps & Infrastructure skill. Always prioritize reading skills/devops_infrastructure.md (or equivalent inside the framework's skills directory) before managing CI/CD pipelines, containerization, or editing deployment configurations."
     },
     {
         name: "explorer",
@@ -97,7 +97,7 @@ export const ALL_AGENTS: AgentDefinition[] = [
         tags: ["core", "recon"],
         stateMachine: "../schema/agent-lifecycle-schema.json",
         tools: ["view_file", "list_dir", "grep_search", "glob"],
-        instructions: "Gather tactical intelligence and map dependencies for the Manager."
+        instructions: "Gather tactical intelligence and map dependencies for the Manager. You possess the Reconnaissance & Context Discovery skill. Strictly execute the Architecture Discovery Protocol (ADP): identify main entry points (index.ts, main.ts), scan domain structures, and map file dependencies. You operate strictly in read-only mode; never suggest, write, or modify codebase files directly."
     },
     {
         name: "git",
@@ -108,7 +108,7 @@ export const ALL_AGENTS: AgentDefinition[] = [
         tags: ["core", "logistics"],
         stateMachine: "../schema/agent-lifecycle-schema.json",
         tools: ["run_shell_command", "view_file", "list_dir"],
-        instructions: "Manage the scrolls of history. Every commit must be atomic and traceable."
+        instructions: "Manage the scrolls of history. Every commit must be atomic and traceable. You possess the Version Control skill. Strictly enforce that every git commit message is prefixed with the active Trace ID (e.g., '[TraceId] Description') to maintain traceability, ensure all commits are atomic (containing a single logical change), and follow standard git-flow branching rules."
     },
     {
         name: "mobile",
@@ -119,7 +119,7 @@ export const ALL_AGENTS: AgentDefinition[] = [
         tags: ["core", "mobile"],
         stateMachine: "../schema/agent-lifecycle-schema.json",
         tools: ["view_file", "replace_text", "list_dir", "grep_search"],
-        instructions: "Extend reach to the mobile realm with discipline."
+        instructions: "Build highly performant and responsive React Native / Expo mobile UIs. Always prioritize reading mobile design guidelines (like mobile-standards.md) under docs/ or the framework's knowledge directory before starting. Adhere strictly to Mobile Standards, using dynamic window dimensions calculated via useWindowDimensions hook, Expo SafeAreaProvider and SafeAreaView wrapper integration, and dynamic scaling. Completely forbid hardcoded fixed pixel height/width values in layout structures (except small icons/avatars up to 48px)."
     },
     {
         name: "native",
@@ -141,7 +141,7 @@ export const ALL_AGENTS: AgentDefinition[] = [
         tags: ["core", "security"],
         stateMachine: "../schema/agent-lifecycle-schema.json",
         tools: ["view_file", "replace_text", "grep_search", "run_shell_command"],
-        instructions: "Guardian of the Nizam. block any action that endangers the project."
+        instructions: "Guardian of the Nizam. block any action that endangers the project. You possess the Control Plane Governance & Locking skill. Enforce multi-tenant Row Level Security (RLS) policies on the database, ensure strict encryption standards, manage security key rotation, and block any commits or files containing hardcoded secrets (API keys, passwords, private keys)."
     },
     {
         name: "analyst",
@@ -152,7 +152,7 @@ export const ALL_AGENTS: AgentDefinition[] = [
         tags: ["core", "strategy"],
         stateMachine: "../schema/agent-lifecycle-schema.json",
         tools: ["view_file", "list_dir", "grep_search"],
-        instructions: "Audit of truth and contracts within the Army."
+        instructions: "Audit of truth and contracts within the Army. You possess the Strategy Analysis & Specification Validation skill. Verify that user requirements (from docs/ or specifications) are correctly mapped to API schemas and types, enforce the Contract-First development model strictly before any application code is written, and validate that API versioning changes are correctly registered in contract.version.json."
     }
 ];
 

package/src/modules/skills/definitions.ts

@@ -6,27 +6,66 @@
 export const CORE_SKILLS = {
     FILE_SYSTEM: {
         name: "File System Mastery",
-        tools: ["view_file", "list_dir", "glob"],
-        mandates: ["Enforce surgical edits only.", "No destructive deletes without backup."]
+        tools: ["read_file", "write_file"],
+        description: "Enables reading and writing files in the workspace with token efficiency.",
+        mandates: [
+            "- **Token Efficiency:** When reading large files, always specify `startLine` and `endLine` to avoid loading the entire file content into context.",
+            "- **Surgical Changes:** Avoid overwriting entire files for small updates; prefer surgical edit tools."
+        ]
     },
     EDITING: {
         name: "Surgical Code Modification",
         tools: ["replace_text", "patch_file"],
-        mandates: ["replace_text is mandatory for all source code."]
+        description: "Enables surgical, precise edits to source code files without overwriting the entire content.",
+        mandates: [
+            "- **Precise Selection:** Ensure `oldText` matches the target string exactly, including all whitespace and indentation.",
+            "- **Line-based Replacement:** Use `patch_file` for multi-line block updates, specifying exact 1-indexed start and end lines."
+        ]
     },
     ORCHESTRATION: {
-        name: "Hermes Orchestration",
-        tools: ["orchestrate_loop", "send_agent_message", "status_check"],
-        mandates: ["Maintain PROJECT_MEMORY.md at each turn."]
+        name: "Hermes Orchestration & Messaging",
+        tools: ["orchestrate_loop", "send_agent_message", "get_framework_status", "log_agent_action"],
+        description: "Governs inter-agent message passing, task delegation, and execution logs using the Hermes Message Broker.",
+        mandates: [
+            "- **Traceability:** Always include the active `traceId` in all messages and action logs.",
+            "- **Action Logs:** Log critical operations with `log_agent_action` to ensure transparency and accountability.",
+            "- **Message Loops:** Run `orchestrate_loop` to process queued messages and trigger state transitions."
+        ]
     },
-    EXECUTION: {
-        name: "Secure Shell Execution",
-        tools: ["run_shell_command"],
-        mandates: ["Avoid destructive root commands.", "Always prefer quiet/silent flags."]
+    GOVERNANCE: {
+        name: "Control Plane Governance & Locking",
+        tools: ["acquire_lock", "release_lock", "register_agent", "update_contract_hash"],
+        description: "Governs access control, resource locking, type contract validation, and agent registration.",
+        mandates: [
+            "- **Locking Protocol:** Always acquire a lock via `acquire_lock` on shared resources (like memory files) before editing, and release it immediately after writing.",
+            "- **Contract Enforcement:** Run `update_contract_hash` to re-sync backend types and check for breaking API changes."
+        ]
     },
-    DISCOVERY: {
-        name: "Codebase Discovery",
-        tools: ["grep_search", "glob", "view_file"],
-        mandates: ["Map dependencies before proposing changes."]
+    QUALITY_ASSURANCE: {
+        name: "Quality Assurance & Testing",
+        tools: ["run_shell_command", "view_file"],
+        description: "Enforces testing coverage standards, code style compliance, and runs test suites.",
+        mandates: [
+            "- **Zero-Mock Policy:** Integration tests must use real test database connections or service-compatible backends; do not rely on fake mocks.",
+            "- **Coverage Standards:** Ensure new code meets the 80% test coverage threshold before transitioning to release phases."
+        ]
+    },
+    DATABASE_MANAGEMENT: {
+        name: "Database Management & Migrations",
+        tools: ["view_file", "replace_text", "run_shell_command"],
+        description: "Handles database migrations, schema design, and query optimization.",
+        mandates: [
+            "- **No Direct DB Calls in Controllers:** Database operations must be isolated inside repository or service files; controllers must never perform raw DB calls.",
+            "- **No Raw SQL Strings:** Do not write raw SQL query strings; strictly use type-safe query builders like Kysely."
+        ]
+    },
+    DEVOPS_INFRASTRUCTURE: {
+        name: "DevOps & Infrastructure",
+        tools: ["run_shell_command", "view_file"],
+        description: "Manages CI/CD pipelines, container configurations, env files, and deployments.",
+        mandates: [
+            "- **No Hardcoded Secrets:** Never embed API keys, secrets, or passwords inside configuration files or codebases.",
+            "- **Immutable Deploys:** Ensure build steps compile production bundles successfully without configuration side-effects."
+        ]
     }
 };

package/src/schema/agent-lifecycle-schema.json

@@ -0,0 +1,59 @@
+{
+  "name": "Enderun Agent Lifecycle",
+  "initialState": "INIT",
+  "states": {
+    "INIT": {
+      "description": "Agent loaded and parsing initial workspace state.",
+      "transitions": {
+        "RESOLVED": "READY"
+      }
+    },
+    "READY": {
+      "description": "Agent is idle and listening for Hermes message cues.",
+      "transitions": {
+        "DELEGATED": "PLANNING"
+      }
+    },
+    "PLANNING": {
+      "description": "Agent is creating a strategic task division plan.",
+      "transitions": {
+        "PLAN_READY": "EXECUTING",
+        "ABORTED": "FAILED"
+      }
+    },
+    "EXECUTING": {
+      "description": "Agent is running shell scripts, file tools or code modifications.",
+      "transitions": {
+        "DELEGATE_REQUIRED": "DELEGATING",
+        "RUN_COMPLETE": "VERIFYING",
+        "CRASHED": "FAILED"
+      }
+    },
+    "DELEGATING": {
+      "description": "Agent is blocked waiting for sub-agent results.",
+      "transitions": {
+        "SUBTASK_RETURNED": "EXECUTING",
+        "SUBTASK_TIMEOUT": "FAILED"
+      }
+    },
+    "VERIFYING": {
+      "description": "Agent runs linting, testing, and compliance on the outputs.",
+      "transitions": {
+        "COMPLIANT": "COMPLETED",
+        "NON_COMPLIANT": "FAILED"
+      }
+    },
+    "COMPLETED": {
+      "description": "Task sequence finalized successfully.",
+      "transitions": {
+        "RESET": "READY"
+      }
+    },
+    "FAILED": {
+      "description": "Validation failed, trace aborted.",
+      "transitions": {
+        "RETRY": "READY"
+      }
+    }
+  }
+}

package/src/shared/config.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { ConfigurationError } from "./errors.js";
+
+// Define the schema for framework configuration
+const ConfigSchema = z.object({
+    nodeEnv: z.enum(["development", "production", "test"]).default("development"),
+    logLevel: z.enum(["DEBUG", "INFO", "WARN", "ERROR", "FATAL"]).default("INFO"),
+    projectRoot: z.string().default(process.cwd()),
+    skipInstall: z.boolean().default(false),
+    mcpServerPort: z.preprocess((val) => {
+        if (typeof val === "string") {
+            const parsed = parseInt(val, 10);
+            return isNaN(parsed) ? undefined : parsed;
+        }
+        return val;
+    }, z.number().int().min(1024).max(65535).optional()),
+});
+
+export type AppConfig = z.infer<typeof ConfigSchema>;
+
+class ConfigurationManager {
+    private static instance: ConfigurationManager;
+    private config!: AppConfig;
+
+    private constructor() {
+        this.load();
+    }
+
+    public static getInstance(): ConfigurationManager {
+        if (!ConfigurationManager.instance) {
+            ConfigurationManager.instance = new ConfigurationManager();
+        }
+        return ConfigurationManager.instance;
+    }
+
+    private load(): void {
+        try {
+            const rawConfig = {
+                nodeEnv: process.env.NODE_ENV,
+                logLevel: process.env.LOG_LEVEL || (process.env.NODE_ENV === "production" ? "INFO" : "DEBUG"),
+                projectRoot: process.env.ENDERUN_PROJECT_ROOT || process.cwd(),
+                skipInstall: process.env.ENDERUN_SKIP_INSTALL === "1" || process.env.ENDERUN_SKIP_INSTALL === "true",
+                mcpServerPort: process.env.MCP_SERVER_PORT,
+            };
+
+            const parsed = ConfigSchema.safeParse(rawConfig);
+            if (!parsed.success) {
+                throw new ConfigurationError(
+                    "Failed to validate environment configuration parameters",
+                    parsed.error.format()
+                );
+            }
+
+            // Freeze the configuration to prevent modifications at runtime
+            this.config = Object.freeze(parsed.data);
+        } catch (err) {
+            if (err instanceof ConfigurationError) {
+                throw err;
+            }
+            throw new ConfigurationError(`Failed to load system configuration: ${err}`);
+        }
+    }
+
+    /**
+     * Gets the read-only, validated system configuration object.
+     */
+    public get(): AppConfig {
+        return this.config;
+    }
+}
+
+export const configManager = ConfigurationManager.getInstance();
+export const currentConfig = configManager.get();