agent-enderun 0.7.2 → 0.7.5

package/.enderun/knowledge/corporate-governance/backend-high-risk-endpoint-guide.md

@@ -0,0 +1,125 @@
+# High-Risk Endpoint Implementation Guide (@backend)
+
+**Applies to**: Any backend endpoint that performs privileged or high-risk administrative actions.
+
+**Goal**: Provide @backend with a concrete, production-grade implementation pattern that strictly enforces corporate governance.
+
+---
+
+## 1. Required Imports and Types
+
+```ts
+import { 
+  UserID, 
+  RoleID, 
+  ManagerApproval, 
+  HighRiskActionPayload 
+} from '../types';
+import { HighRiskActionRequiresApprovalError } from '../types/errors';
+import { auditLogRepository } from '../repositories/audit-log.repository';
+```
+
+---
+
+## 2. High-Risk Endpoint Pattern (Recommended Structure)
+
+```ts
+// apps/backend/src/routes/users/promote-to-superadmin.route.ts
+
+interface PromoteToSuperAdminBody extends HighRiskActionPayload {
+  userId: UserID;
+  newRole: 'SuperAdmin';
+}
+
+fastify.post('/api/v1/users/:id/promote-to-superadmin', async (request, reply) => {
+  const { id } = request.params;
+  const body = request.body as PromoteToSuperAdminBody;
+
+  // === MANDATORY HIGH-RISK GOVERNANCE CHECK ===
+  if (!body.isHighRiskAdminAction || !body.managerApproval) {
+    throw new HighRiskActionRequiresApprovalError(
+      'Promotion to SuperAdmin is a high-risk action',
+      { requiredFields: ['isHighRiskAdminAction', 'managerApproval'] }
+    );
+  }
+
+  // Validate managerApproval structure
+  const approval = body.managerApproval;
+  if (approval.approvedBy !== 'manager') {
+    throw new HighRiskActionRequiresApprovalError('Approval must be issued by @manager');
+  }
+
+  // Optional: Add time-based or policy-based validation here
+  // (e.g., approval must be less than 15 minutes old)
+
+  const targetUserId = id as UserID;
+
+  // === EXECUTE THE PRIVILEGED ACTION ===
+  const updatedUser = await userService.promoteToSuperAdmin(targetUserId);
+
+  // === AUDIT LOGGING (MANDATORY) ===
+  await auditLogRepository.create({
+    traceId: approval.traceId,
+    actorId: request.user.id as UserID,           // the person who triggered the action
+    action: 'USER_PROMOTED_TO_SUPERADMIN',
+    targetId: targetUserId,
+    beforeState: { role: updatedUser.previousRole },
+    afterState: { role: 'SuperAdmin' },
+    managerApprovalId: approval.approvalId,
+    reason: approval.reason,
+  });
+
+  return {
+    success: true,
+    user: updatedUser,
+    approvalUsed: approval.approvalId,
+  };
+});
+```
+
+---
+
+## 3. Error Handling
+
+Always throw typed domain errors:
+
+- Use `HighRiskActionRequiresApprovalError` when governance requirements are not met.
+- Never return generic 403 or 400 with vague messages.
+
+---
+
+## 4. Testing Requirements (Testable Rules)
+
+Every high-risk endpoint **must** have the following test cases:
+
+- [ ] Request without `isHighRiskAdminAction` → `HighRiskActionRequiresApprovalError`
+- [ ] Request without `managerApproval` → `HighRiskActionRequiresApprovalError`
+- [ ] `managerApproval.approvedBy !== 'manager'` → `HighRiskActionRequiresApprovalError`
+- [ ] Valid approval token → Action succeeds + audit log is created
+- [ ] Valid approval but action fails later → Audit log still created with failure status (if possible)
+
+---
+
+## 5. Anti-Patterns (Strictly Forbidden)
+
+- Bypassing validation “because the frontend already checked”
+- Logging the full `managerApproval.signature` in normal logs
+- Skipping audit logging for “internal admin users”
+- Using plain `string` for `userId` or `approvalId` inside the endpoint
+- Returning raw error objects to the client
+
+---
+
+## 6. Integration Points
+
+This pattern must be combined with:
+- `domain-error-handling-standard.md`
+- `audit-logging-standard.md`
+- `branded-types-law.md`
+
+@backend is responsible for refusing to implement any high-risk feature until the above three standards are satisfied in the design.
+
+**Reference files** (must be read before implementation):
+- `high-risk-actions-managerapproval.md`
+- `high-risk-action-approval-flow-simulation.md`
+- `corporate-project-scaffolding-sop.md`

package/.enderun/knowledge/corporate-governance/branded-types-law.md

@@ -0,0 +1,77 @@
+# Branded Types Law
+
+**Status:** Mandatory — Zero Tolerance
+
+## Why This Exists
+Plain `string` or `number` for identifiers (user IDs, role IDs, approval tokens, etc.) is a major source of bugs and security issues in large systems. Agent Enderun enforces **Branded Types** to make domain identifiers type-safe at compile time.
+
+## Definition
+```ts
+type Brand<T, BrandName extends string> = T & { readonly __brand: BrandName };
+
+type UserID = Brand<string, 'UserID'>;
+type RoleID = Brand<string, 'RoleID'>;
+type ApprovalID = Brand<string, 'ApprovalID'>;
+```
+
+## Rules
+1. Every identifier that represents a domain entity **must** be a branded type.
+2. Backend is the source of truth (`apps/backend/src/types`).
+3. Frontend must maintain an exact local copy and update it when notified via Hermes.
+4. Never cast `as any` or use `string` directly when a branded type is available.
+5. Database columns can remain as strings, but the TypeScript layer must brand them immediately after reading.
+
+## Enforcement
+- @backend must refuse to implement any feature that introduces non-branded IDs.
+- @analyst will run static analysis to detect violations.
+- Any PR that introduces plain strings for IDs must be rejected.
+
+## Example Correct Usage
+```ts
+const promoteUser = async (userId: UserID, newRole: SystemRole, approval: ManagerApproval) => { ... }
+```
+
+## Recommended Folder Structure
+
+```
+apps/backend/src/types/
+├── brand.ts                 # Generic Brand utility
+├── identifiers.ts           # UserID, RoleID, ApprovalID, TraceID...
+├── approval.ts              # ManagerApproval + HighRiskActionPayload
+├── errors.ts                # DomainError hierarchy
+├── user.ts
+├── role.ts
+└── index.ts                 # Re-exports
+```
+
+## Concrete Implementation Examples
+
+**brand.ts**
+```ts
+export type Brand<T, BrandName extends string> = T & { readonly __brand: BrandName };
+```
+
+**identifiers.ts**
+```ts
+import { Brand } from './brand';
+
+export type UserID = Brand<string, 'UserID'>;
+export type RoleID = Brand<string, 'RoleID'>;
+export type ApprovalID = Brand<string, 'ApprovalID'>;
+export type TraceID = Brand<string, 'TraceID'>;
+```
+
+## Common Anti-Patterns (Forbidden)
+- `userId: string`
+- `roleId: number`
+- Passing raw database rows directly to the frontend without branding
+- Using `as any` to bypass branded type checks
+- Casting database IDs directly without branding at the repository layer
+
+## Testable Rules (for @analyst)
+
+- Static analysis must fail on any non-branded identifier used in public APIs or service methods.
+- All identifiers in `apps/backend/src/types` must extend the `Brand` utility.
+- Frontend type copies must match backend branded types exactly (contract drift detection).
+
+This law is non-negotiable for any project using Agent Enderun at enterprise scale.

package/.enderun/knowledge/corporate-governance/contract-drift-detection-simulation.md

@@ -0,0 +1,92 @@
+# Contract Drift Detection & Resolution Simulation
+
+**Purpose**: This simulation shows how @analyst, @backend, @frontend, and @manager should handle a contract drift situation in a corporate project according to Agent Enderun standards.
+
+**Scenario**: During development of the User Management module, @backend adds a new required field `lastLoginAt` to the `User` type without notifying the team.
+
+---
+
+## Step 1 – Drift is Detected
+
+**@analyst** runs the contract integrity check (as per its responsibilities in the Corporate Project Scaffolding SOP).
+
+**Detection**:
+- `apps/backend/src/types/user.ts` has changed.
+- `apps/web/src/types/api-contracts.ts` (frontend copy) does not contain the new field.
+- Hash in `contract.version.json` has not been updated.
+
+**@analyst** sends a Hermes message to @manager and @frontend:
+
+```json
+{
+  "type": "contract_drift_detected",
+  "traceId": "TRACE-20260525-CONTRACT-DRIFT-007",
+  "payload": {
+    "changedFile": "apps/backend/src/types/user.ts",
+    "newField": "lastLoginAt: string",
+    "frontendCopyStatus": "outdated",
+    "severity": "high"
+  }
+}
+```
+
+---
+
+## Step 2 – @manager Assessment
+
+**@manager** receives the notification and loads:
+- `branded-types-law.md`
+- `corporate-project-scaffolding-sop.md`
+
+**@manager response**:
+
+This is a contract drift. Per our governance rules, no one may continue implementation on the affected feature until the drift is resolved.
+
+**Immediate actions**:
+1. @backend must pause any work depending on the new field.
+2. @frontend must be briefed to update the local type copy.
+3. @analyst will verify the fix and update the contract version.
+
+I am now issuing a formal pause on the User detail feature until resolution.
+
+---
+
+## Step 3 – Resolution Process
+
+**@backend** (after receiving the briefing):
+
+Understood. I will not merge or continue work using the new field until the contract is synchronized.
+
+**@frontend**:
+
+I have updated `apps/web/src/types/api-contracts.ts` to include `lastLoginAt`.
+
+**@analyst**:
+
+- Verified that both backend and frontend types now match.
+- Updated `contract.version.json` (MINOR version bump).
+- Confirmed no other files are affected.
+
+**@manager** (final resolution message):
+
+Contract drift resolved.
+
+- Backend and frontend types are now in sync.
+- Contract version updated.
+- Feature development on the affected area may resume.
+
+All future type changes must follow the Hermes notification process defined in the Scaffolding SOP.
+
+---
+
+## Lessons from This Simulation
+
+- Contract drift is treated as a serious governance issue.
+- @analyst has real authority to pause work.
+- @manager uses the standards to protect the project from technical debt.
+- Resolution must be documented (even if small) in PROJECT_MEMORY.md.
+
+**Reference files**:
+- `branded-types-law.md`
+- `corporate-project-scaffolding-sop.md`
+- `corporate-project-kickoff-checklist.md`

package/.enderun/knowledge/corporate-governance/corporate-governance-playbook.md

@@ -0,0 +1,89 @@
+# Corporate Governance Playbook
+
+**Version**: 1.0  
+**Purpose**: This is the single master reference that ties together all corporate governance standards for Agent Enderun. It provides navigation, summaries, and the recommended order of study for agents and teams.
+
+---
+
+## Core Philosophy
+
+We do not ship pre-built applications.  
+We internalize strong governance patterns into the agents so they can guide any corporate project correctly from the first day.
+
+---
+
+## Document Hierarchy
+
+### Foundational Laws & Standards
+| Document | Focus | Must Read By |
+|----------|-------|--------------|
+| `branded-types-law.md` | Compile-time safety for identifiers | All agents |
+| `high-risk-actions-managerapproval.md` | Protection of privileged operations | All agents |
+| `domain-error-handling-standard.md` | Typed, safe error system | @backend, @analyst |
+| `audit-logging-standard.md` | Tamper-evident privileged action records | @backend, @analyst, @manager |
+
+### UI & Coordination Patterns
+| Document | Focus | Must Read By |
+|----------|-------|--------------|
+| `high-risk-security-modal-hermes-flow.md` | Frontend high-risk action handling | @frontend, @manager |
+| `frontend-high-risk-modal-guide.md` | Concrete component + hook implementation | @frontend |
+
+### Backend Implementation
+| Document | Focus | Must Read By |
+|----------|-------|--------------|
+| `backend-high-risk-endpoint-guide.md` | Production-grade high-risk endpoint pattern | @backend |
+
+### Process & Scaffolding
+| Document | Focus | Must Read By |
+|----------|-------|--------------|
+| `corporate-project-scaffolding-sop.md` | Step-by-step process for new corporate projects | @manager (primary) |
+| `corporate-project-kickoff-checklist.md` | Mandatory checklist at project start | @manager + team |
+| `governance-baseline-briefing-template.md` | First-day briefing text | @manager |
+| `manager-first-three-briefings.md` | Ready templates for early project phases | @manager |
+
+### Simulations (Learning & Reference)
+| Document | Focus |
+|----------|-------|
+| `corporate-project-kickoff-simulation.md` | Full multi-session project start example |
+| `high-risk-action-approval-flow-simulation.md` | End-to-end high-risk action cycle |
+| `contract-drift-detection-simulation.md` | How to detect and resolve contract drift |
+
+### Analyst & Compliance
+| Document | Focus |
+|----------|-------|
+| `analyst-contract-integrity-guide.md` | @analyst’s verification responsibilities and processes |
+
+---
+
+## Recommended Reading Order (for New Projects)
+
+1. **@manager** (before anything else)
+   - `corporate-project-scaffolding-sop.md`
+   - `corporate-project-kickoff-checklist.md`
+   - `governance-baseline-briefing-template.md`
+
+2. **All Agents**
+   - `branded-types-law.md`
+   - `high-risk-actions-managerapproval.md`
+
+3. **Specialist Agents**
+   - @backend → `backend-high-risk-endpoint-guide.md` + `domain-error-handling-standard.md`
+   - @frontend → `frontend-high-risk-modal-guide.md`
+   - @analyst → `analyst-contract-integrity-guide.md`
+
+4. **Simulations** (for deeper understanding)
+   - Start with `corporate-project-kickoff-simulation.md`
+
+---
+
+## When to Reference This Playbook
+
+- At the start of every new corporate project
+- When any high-risk feature is being planned
+- During contract changes
+- When @analyst detects governance or contract issues
+- During project retrospectives
+
+---
+
+**This playbook is the single source of truth for corporate governance in Agent Enderun.**

package/.enderun/knowledge/corporate-governance/corporate-project-kickoff-checklist.md

@@ -0,0 +1,56 @@
+# Corporate Project Kickoff Checklist
+
+**Owner:** @manager  
+**Audience:** Human user + all specialist agents
+
+This checklist must be completed (and documented in `PROJECT_MEMORY.md`) at the very beginning of any corporate or enterprise-grade project.
+
+---
+
+## Phase 0 – Governance Alignment
+
+- [ ] @manager has read all files in `.gemini/knowledge/corporate-governance/`
+- [ ] User has been given the Governance Baseline Briefing
+- [ ] User has explicitly acknowledged the corporate standards
+- [ ] Decision recorded in `PROJECT_MEMORY.md` under "Critical Decisions"
+
+## Phase 1 – Project Structure & Contracts
+
+- [ ] `apps/backend/src/types` folder structure created
+- [ ] Branded Types utility + core identifiers defined
+- [ ] `ManagerApproval` and `HighRiskActionPayload` interfaces defined
+- [ ] `contract.version.json` initialized
+- [ ] @frontend has created matching type copies in `apps/web/src/types`
+- [ ] @analyst has been briefed on contract integrity responsibility
+
+## Phase 2 – High-Risk Governance Infrastructure (if privileged operations expected)
+
+- [ ] High-risk validation logic designed for @backend
+- [ ] Security Modal + Hermes briefing flow designed for @frontend
+- [ ] Audit logging strategy defined (see audit-logging-standard.md)
+- [ ] Domain Error hierarchy created (including `HighRiskActionRequiresApprovalError`)
+- [ ] Both @backend and @frontend agents have received explicit briefings referencing the knowledge files
+
+## Phase 3 – Tooling & Process
+
+- [ ] @analyst has confirmed contract drift detection process
+- [ ] Documentation ownership rule explained (all architecture decisions go to `docs/architecture/decisions/`)
+- [ ] First ADR (Architecture Decision Record) created for governance baseline
+- [ ] @manager has updated `PROJECT_MEMORY.md` with initial trace and active tasks
+
+## Phase 4 – Team Alignment
+
+- [ ] All active agents have loaded the latest versions of:
+  - `branded-types-law.md`
+  - `high-risk-actions-managerapproval.md`
+  - `high-risk-security-modal-hermes-flow.md`
+  - `audit-logging-standard.md`
+  - `domain-error-handling-standard.md`
+- [ ] @manager has confirmed that no specialist agent may begin implementation work until the above items are complete
+
+---
+
+**@manager Note**:  
+Do not proceed to feature development until this checklist is fully completed and acknowledged by the user. Shortcuts at this stage create expensive technical debt later.
+
+Mark items as done in `PROJECT_MEMORY.md` under a dedicated "Kickoff Checklist" section.

package/.enderun/knowledge/corporate-governance/corporate-project-kickoff-simulation.md

@@ -0,0 +1,144 @@
+# Corporate Project Kickoff Simulation
+
+**Purpose**: This document provides a realistic, step-by-step simulation of how @manager should conduct the first sessions when a user starts a new corporate/enterprise project using Agent Enderun.
+
+**Scenario**: A company wants to build an internal "Enterprise User & Access Management" platform. The project will have normal CRUD operations plus high-risk administrative actions (role elevation, system configuration changes).
+
+---
+
+## Session 1 – Initial Contact & Governance Baseline
+
+**User**:  
+"Hi, I need to build a user management system for our company. It should support roles like User, Admin, and SuperAdmin. Admins should be able to promote users, but promoting to SuperAdmin should be very controlled."
+
+**@manager (after loading all corporate-governance knowledge)**:
+
+Thank you. Before we discuss any features or technology, we need to establish the governance foundation for this project.
+
+This appears to be a corporate/enterprise project involving privileged operations. Therefore, we will follow Agent Enderun’s corporate standards from day one.
+
+The non-negotiable pillars are:
+
+1. **Branded Types** for all identifiers (see `branded-types-law.md`)
+2. **High-Risk Administrative Actions** protected by explicit `managerApproval` + Hermes coordination (see `high-risk-actions-managerapproval.md`)
+3. **Contract-first development** — types before implementation
+4. **Audit logging** for all privileged operations (see `audit-logging-standard.md`)
+5. **Typed Domain Errors** instead of generic exceptions (see `domain-error-handling-standard.md`)
+
+These standards exist to make the system safe, auditable, and maintainable at scale.
+
+I have prepared the **Corporate Project Kickoff Checklist**. We will go through the relevant parts together over the next sessions.
+
+Do you accept these operating rules for this project?
+
+**User**:  
+"Yes, that makes sense. We need proper controls especially around SuperAdmin promotions."
+
+**@manager**:
+Excellent. Acknowledgment recorded.
+
+We will now begin Phase 0 and Phase 1 of the Corporate Project Scaffolding SOP.
+
+First action: We will establish the type foundation before writing any feature code.
+
+---
+
+## Session 2 – Contract & Type Foundation
+
+**@manager** (briefing to @backend and @frontend):
+
+Team,
+
+We are now in Phase 1 of the Corporate Project Scaffolding SOP.
+
+Required immediate deliverables:
+
+**@backend**:
+- Create `apps/backend/src/types/brand.ts`
+- Create `apps/backend/src/types/identifiers.ts` with `UserID`, `RoleID`, `ApprovalID`, `TraceID`
+- Create `apps/backend/src/types/approval.ts` with `ManagerApproval` and `HighRiskActionPayload`
+- Create `apps/backend/src/types/errors.ts` including `HighRiskActionRequiresApprovalError`
+- Initialize `apps/backend/contract.version.json`
+
+**@frontend**:
+- Create matching type copies in `apps/web/src/types/api-contracts.ts`
+- Begin designing the base `HighRiskSecurityModal` component structure (implementation will come in Phase 2)
+
+**@analyst**:
+- Establish contract integrity verification process
+
+No backend routes or frontend pages may be implemented until these contracts are defined and approved by me.
+
+Please confirm when the type foundation is ready for review.
+
+---
+
+## Session 3 – High-Risk Governance Infrastructure
+
+**User**:  
+"We need to implement the 'Promote to SuperAdmin' feature soon."
+
+**@manager**:
+
+Understood. However, according to the Corporate Project Scaffolding SOP (Phase 2), we must build the high-risk governance infrastructure **before** implementing any privileged feature.
+
+This means:
+
+- @backend must implement strict validation that rejects any role elevation request unless `isHighRiskAdminAction: true` + valid `managerApproval` is present.
+- @frontend must build a prominent, non-dismissible Security Modal that forces the user to provide a reason before initiating the Hermes briefing to me (@manager).
+- Audit logging must be designed for every high-risk action (see `audit-logging-standard.md`).
+
+Only after these two layers exist will we proceed to implement the actual promotion feature.
+
+@backend and @frontend — I am now issuing the official briefing for Phase 2.
+
+Please reference:
+- `high-risk-actions-managerapproval.md`
+- `high-risk-security-modal-hermes-flow.md`
+- `domain-error-handling-standard.md`
+
+Confirm when the infrastructure design is ready for my approval.
+
+---
+
+## Session 4 – Delegation Example (After Infrastructure Approval)
+
+**@manager** (to @backend):
+
+@backend,
+
+The high-risk infrastructure has been approved.
+
+You may now implement the following:
+
+**Feature**: `POST /api/v1/users/:id/role`
+
+Requirements:
+- Must use branded types only (`UserID`, `RoleID`, `ApprovalID`)
+- Must reject the request with `HighRiskActionRequiresApprovalError` if the high-risk payload is missing or invalid
+- Must create an audit log entry using the `AuditLog` domain (see `audit-logging-standard.md`)
+- Must follow the contract defined in `apps/backend/src/types/api-contracts.ts`
+
+Reference files:
+- `high-risk-actions-managerapproval.md`
+- `branded-types-law.md`
+- `domain-error-handling-standard.md`
+
+Do not proceed with any other privileged features until this endpoint is complete and reviewed.
+
+---
+
+## Key Behaviors Demonstrated in This Simulation
+
+- @manager never allows feature work before governance foundation
+- @manager consistently references the knowledge files
+- @manager uses the Corporate Project Kickoff Checklist and Scaffolding SOP as the operating process
+- @manager educates the user while protecting the standards
+- All delegations are precise and reference the corporate governance documents
+
+This is the expected behavior for any corporate project.
+
+---
+
+**Note for Agents**:  
+When conducting real sessions, adapt the language but never skip the governance steps. Shortcuts at the beginning create expensive problems later.

package/.enderun/knowledge/corporate-governance/corporate-project-scaffolding-sop.md

@@ -0,0 +1,103 @@
+# Corporate Enterprise Project Scaffolding SOP (for @manager)
+
+**Version:** 1.1  
+**Purpose**: This is the mandatory standard process that @manager must follow when a user initiates a new project with corporate, enterprise, or regulated characteristics.
+
+**Core Philosophy**:  
+Agent Enderun does **not** ship pre-built reference applications inside `apps/`.  
+Our value is in internalizing governance standards into the agents so that we can **guide the user** to build correctly, step by step, from the very first file.
+
+---
+
+## Phase 0 – Discovery & Governance Baseline (Non-Negotiable First Step)
+
+Before any code is written or any feature is discussed in detail:
+
+1. **Load Corporate Governance Knowledge** (mandatory reads):
+   - `branded-types-law.md`
+   - `high-risk-actions-managerapproval.md`
+   - `high-risk-security-modal-hermes-flow.md`
+   - `audit-logging-standard.md`
+   - `governance-baseline-briefing-template.md`
+   - `audit-logging-standard.md` (when created)
+
+2. **Assess Project Context**:
+   - Does the project involve multiple users, roles, permissions, or privileged operations?
+   - Is there any requirement for audit trails, compliance, or high-risk administrative actions?
+   - Default assumption: Treat every new project as enterprise-grade unless the user explicitly states it is a simple internal prototype with no privileged actions.
+
+3. **Establish the Governance Contract** (before any technical discussion):
+   - Clearly communicate that the project will follow Agent Enderun corporate standards.
+   - Introduce the non-negotiable pillars:
+     - Branded Types for all domain identifiers
+     - High-risk actions protected exclusively by `managerApproval` + Hermes coordination
+     - Contract-first development (types before implementation)
+     - Comprehensive audit logging for privileged operations
+   - Obtain explicit user acknowledgment.
+
+4. **Document the Baseline Decision** in `docs/architecture/decisions/`.
+
+**Rule**: No feature work, no architecture discussion, and no delegation may begin until Phase 0 is complete and acknowledged.
+
+---
+
+## Phase 1 – Foundation Layer (Contracts Before Any Implementation)
+
+1. **Create the Type System First** (`apps/backend/src/types`):
+   - `brand.ts` – Generic `Brand<T, Name>` utility
+   - `identifiers.ts` – `UserID`, `RoleID`, `ApprovalID`, `TraceID`, etc.
+   - `approval.ts` – `ManagerApproval` and `HighRiskActionPayload`
+   - `errors.ts` – DomainError base + concrete errors (including `HighRiskActionRequiresApprovalError`)
+   - `user.ts` / `role.ts` – Core domain entities
+   - `api-contracts.ts` – Initial request/response shapes for the first feature
+
+2. **Initialize Contract Versioning**:
+   - Create `apps/backend/contract.version.json` with proper MAJOR.MINOR version and hash.
+
+3. **Brief Supporting Agents**:
+   - Brief `@analyst` to establish contract integrity verification process.
+   - Brief `@frontend` to create parallel type copies and the base Security Modal component.
+
+**Strict Rule**: No backend route, no React component, and no database schema may be implemented until the relevant contracts are defined and approved by @manager.
+
+---
+
+## Phase 2 – High-Risk Governance Infrastructure (Before Any Privileged Feature)
+
+If the project will contain user/role management, configuration changes, or any privileged operations:
+
+1. Design and document the complete `managerApproval` validation flow with `@backend`.
+2. Design and implement the Security Modal + Hermes briefing user flow with `@frontend`.
+3. Ensure both specialist agents have explicit instructions in their briefings referencing the corporate governance knowledge files.
+4. Verify that `@backend` will reject any high-risk request lacking the proper payload, and that `@frontend` will never bypass the modal.
+
+Only after these two infrastructure layers exist may actual feature development for privileged areas begin.
+
+---
+
+## Phase 3 – Feature Development Under Strict Governance
+
+When delegating any work to `@backend` or `@frontend`:
+
+The briefing message **must** include:
+- Exact path to the contract types for this feature.
+- Classification of whether the feature contains high-risk actions.
+- Explicit references to the relevant files in `.gemini/knowledge/corporate-governance/`.
+- Requirement to notify @manager before implementing any high-risk path.
+- Mandate to produce ADR documentation for any new governance decisions.
+
+After delivery:
+- Require `@analyst` to perform contract alignment verification.
+- Require documentation of the implementation in the project’s decision records.
+
+---
+
+## Phase 4 – Continuous Enforcement & Education
+
+- At the start of every session, re-read the corporate governance knowledge files.
+- Any proposal to “add governance later” or bypass standards must be treated as a process violation and rejected.
+- @manager is responsible for continuously educating the user and the specialist agents on the standards throughout the lifetime of the project.
+
+---
+
+**This SOP is the primary mechanism by which Agent Enderun scales enterprise discipline without shipping example code.**