dhurandhar 1.0.0

package/docs/ARCHITECTURE_V2.md

@@ -0,0 +1,249 @@
+# Dhurandhar v2.0 Architecture
+
+## System Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     ENGINEERING-FIRST LAYER                     │
+│  Principle: Direct action, 3 questions max, no justifications  │
+└─────────────────────────┬───────────────────────────────────────┘
+                          │
+┌─────────────────────────▼───────────────────────────────────────┐
+│                       CLI INTERFACE                              │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
+│  │ install  │  │ service  │  │  entity  │  │ context  │       │
+│  │ (3 Qs)   │  │ (direct) │  │ (direct) │  │(rehydrate)│      │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────┘       │
+└─────────────────────────┬───────────────────────────────────────┘
+                          │
+┌─────────────────────────▼───────────────────────────────────────┐
+│                    CORE LIBRARIES                                │
+│  ┌─────────────────┐  ┌─────────────────┐                      │
+│  │  SDM Manager    │  │ Config Manager  │                      │
+│  │  (persistence)  │  │  (framework)    │                      │
+│  └─────────────────┘  └─────────────────┘                      │
+│  ┌─────────────────┐  ┌─────────────────┐                      │
+│  │ Module Manager  │  │   Validators    │                      │
+│  └─────────────────┘  └─────────────────┘                      │
+└─────────────────────────┬───────────────────────────────────────┘
+                          │
+┌─────────────────────────▼───────────────────────────────────────┐
+│              PERSISTENT STATE (Project Root)                     │
+│  ┌──────────────────────────────────────────────────┐           │
+│  │        SYSTEM_DESIGN_MAP.yaml                    │           │
+│  │  - Metadata (project, architecture)              │           │
+│  │  - Tech Stack (languages, frameworks, DBs)       │           │
+│  │  - User Types (roles, permissions, auth)         │           │
+│  │  - Entities (attributes, relationships)          │           │
+│  │  - Services (scope, stack, API, dependencies)    │           │
+│  │  - Communication (protocols, patterns)           │           │
+│  │  - Infrastructure (deployment, components)       │           │
+│  │  - Build Config (tools, CI/CD)                   │           │
+│  └──────────────────────────────────────────────────┘           │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## Data Flow
+
+### Service Addition Flow
+
+```
+User: "dhurandhar service add 'auth: JWT auth'"
+    │
+    ▼
+CLI (service.js)
+    │
+    ├─→ Parse quick spec: name="auth", scope="JWT auth"
+    │
+    ├─→ Check SDM for context
+    │   └─→ Primary language: Go
+    │   └─→ Existing services: 0
+    │
+    ├─→ Ask technical questions (max 3)
+    │   1. Framework? → Echo (default for Go)
+    │   2. Database? → PostgreSQL (default)
+    │
+    ├─→ Build service object
+    │   {
+    │     name: "auth",
+    │     scope: "JWT auth",
+    │     tech_stack: { language: Go, framework: Echo, db: PostgreSQL },
+    │     api: { type: rest, port: 8080 },
+    │   }
+    │
+    ├─→ SDMManager.addService()
+    │   ├─→ Load SYSTEM_DESIGN_MAP.yaml
+    │   ├─→ Add service to services[]
+    │   ├─→ Update tech_stack summary
+    │   ├─→ Save SYSTEM_DESIGN_MAP.yaml
+    │
+    └─→ Output: "✓ auth-service added: Go/Echo/PostgreSQL on port 8080"
+```
+
+### Context Rehydration Flow
+
+```
+[New Session Starts]
+    │
+    ▼
+Agent/Developer runs: "dhurandhar context"
+    │
+    ▼
+CLI (context.js)
+    │
+    ├─→ SDMManager.getRehydrationContext()
+    │   └─→ Read SYSTEM_DESIGN_MAP.yaml
+    │
+    ├─→ Display architecture summary
+    │   - 3 services (Go/Echo/PostgreSQL)
+    │   - 5 entities
+    │   - Microservices architecture
+    │
+    └─→ Ready for work (0 rediscovery time)
+```
+
+## Schema Hierarchy
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│           design-module-schema.yaml (v2.0)                  │
+│  Defines structure for design modules                       │
+│                                                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
+│  │  User Types  │  │   Entities   │  │   Services   │     │
+│  │              │  │              │  │              │     │
+│  │ - role       │  │ - name       │  │ - name       │     │
+│  │ - permissions│  │ - attributes │  │ - scope      │     │
+│  │ - auth       │  │ - relations  │  │ - tech_stack │     │
+│  └──────────────┘  └──────────────┘  └──────────────┘     │
+└─────────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│        system-design-map-schema.yaml                        │
+│  Defines structure for persistent architecture state        │
+│                                                              │
+│  ┌─────────────────────────────────────────────────┐       │
+│  │  metadata + tech_stack + user_types +           │       │
+│  │  entities + services + communication +          │       │
+│  │  infrastructure + build_config                  │       │
+│  └─────────────────────────────────────────────────┘       │
+└─────────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│           SYSTEM_DESIGN_MAP.yaml (instance)                 │
+│  Actual architecture state for a specific project           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Agent Interaction Model
+
+```
+┌──────────────────────────────────────────────────────────┐
+│            AI Agent (Claude/Augment/Cursor)              │
+│                                                           │
+│  On Session Start:                                       │
+│  1. Read .dhurandhar-agent-config.md                     │
+│  2. Load SYSTEM_DESIGN_MAP.yaml                          │
+│  3. Parse architecture context                           │
+│  4. Ready (context rehydrated)                           │
+└──────────────────┬───────────────────────────────────────┘
+                   │
+                   ▼
+┌──────────────────────────────────────────────────────────┐
+│           User Request Handling                          │
+│                                                           │
+│  User: "Add caching to user-service"                     │
+│                                                           │
+│  Agent:                                                  │
+│  ├─→ Check SDM: user-service exists                     │
+│  ├─→ Check SDM: current stack is Go/Echo/PostgreSQL     │
+│  ├─→ Ask: "Cache: Redis or Memcached?" (Question 1/3)   │
+│  ├─→ User: "Redis"                                       │
+│  ├─→ Update SDM: Add Redis to infrastructure            │
+│  └─→ Confirm: "✓ Redis added to user-service"           │
+│                                                           │
+│  Total questions: 1 (well under 3-question limit)        │
+└──────────────────────────────────────────────────────────┘
+```
+
+## Anti-Pattern Prevention
+
+```
+┌────────────────────────────────────────────────────────────┐
+│                BUSINESS-PROCESS HEAVY ❌                   │
+│                                                             │
+│  User: "Add auth service"                                  │
+│  Agent: "Why do you need authentication?"                  │
+│  User: "For login"                                         │
+│  Agent: "What are your requirements?"                      │
+│  User: "JWT tokens"                                        │
+│  Agent: "Have you considered OAuth2?"                      │
+│  ...                                                        │
+│  [15 minutes later]                                        │
+│  Agent: "OK, adding service..."                            │
+│                                                             │
+│  Result: COGNITIVE FATIGUE ⚠                               │
+└────────────────────────────────────────────────────────────┘
+
+┌────────────────────────────────────────────────────────────┐
+│              ENGINEERING-FIRST ✅                           │
+│                                                             │
+│  User: "Add auth service"                                  │
+│  Agent: [Checks SDM: primary language = Go]                │
+│  Agent: "Framework: Echo, Gin, or Fiber?"                  │
+│  User: "Echo"                                              │
+│  Agent: "✓ auth-service added: Go/Echo/PostgreSQL:8080"    │
+│                                                             │
+│  Result: FAST & FOCUSED ✓                                  │
+└────────────────────────────────────────────────────────────┘
+```
+
+## Comparison: v1.0 vs v2.0
+
+```
+┌─────────────────┬──────────────────┬──────────────────┐
+│   Dimension     │   v1.0 (Bmad)    │  v2.0 (Eng-1st) │
+├─────────────────┼──────────────────┼──────────────────┤
+│ Philosophy      │ Modular skills   │ Tech specs       │
+│ Interaction     │ Exploratory      │ Direct action    │
+│ Questions       │ Unlimited        │ Max 3            │
+│ Context         │ Lost b/w sessions│ Persistent (SDM) │
+│ Focus           │ Organization     │ Implementation   │
+│ Speed           │ Hours            │ Minutes          │
+│ Cognitive load  │ High             │ Minimal          │
+└─────────────────┴──────────────────┴──────────────────┘
+```
+
+## Key Principles Enforced
+
+1. **Context Rehydration First**
+   - Always read SYSTEM_DESIGN_MAP.yaml before responding
+   - Load complete architecture state
+   - No rediscovery needed
+
+2. **Direct Action Over Discussion**
+   - User requests → immediate technical clarification
+   - No "why" questions
+   - No alternative exploration (unless requested)
+
+3. **Technical Specifications Only**
+   - Language, framework, database
+   - API type, ports, protocols
+   - Entity attributes, relationships
+   - Service dependencies
+
+4. **Three-Question Limit**
+   - Maximum 3 technical questions per component
+   - Use SDM context to minimize questions
+   - Auto-select sensible defaults
+
+5. **Brief Confirmations**
+   - One-line status updates
+   - No verbose explanations
+   - Implementation over discussion
+
+---
+
+**Dhurandhar v2.0: Persistent Context + Direct Action = Zero Cognitive Fatigue**

package/docs/DECISION_REGISTRY.md

@@ -0,0 +1,357 @@
+# Technical Decision Registry
+
+## Overview
+
+Dhurandhar v2.5 introduces the **Technical Decision Registry** - a Bmad-Method-inspired "stock of decisions" that eliminates cognitive fatigue by storing all technical conventions ONCE and applying them automatically everywhere.
+
+## Philosophy
+
+### Traditional Approach (Anti-Pattern)
+
+```
+Developer 1: "Should classes be PascalCase or snake_case?"
+Team: [30 minute debate]
+Decision: "PascalCase"
+
+[Two weeks later]
+
+Developer 2: "Should classes be PascalCase or snake_case?"
+Team: "Didn't we already decide this?"
+Developer 2: "Where is it documented?"
+Team: [Another 30 minute debate]
+
+[Repeated for every basic convention]
+```
+
+### Dhurandhar Approach
+
+```
+Lead System Architect: "Stock all decisions during install"
+
+dhurandhar decisions --stock
+
+? Class naming: PascalCase
+? Function naming: camelCase
+? Database tables: snake_case
+? Error format: Standard envelope
+? Logging: Structured JSON
+
+✓ All decisions stocked
+
+[Never asked again. Automatically applied to all code.]
+```
+
+## Decision Categories
+
+### 1. Naming Conventions
+
+**Purpose**: Eliminate debates about case styles, file names, prefixes
+
+**Decisions Stocked**:
+```yaml
+naming_conventions:
+  case_styles:
+    classes: PascalCase          # UserService, OrderController
+    functions: camelCase          # getUserById, createOrder
+    variables: camelCase          # userId, orderTotal
+    constants: SCREAMING_SNAKE_CASE  # MAX_RETRIES, API_URL
+    database_tables: snake_case   # users, order_items
+    database_columns: snake_case  # user_id, created_at
+    api_endpoints: kebab-case     # /api/v1/user-profiles
+  
+  file_patterns:
+    components: "ComponentName.tsx"
+    services: "ServiceName.service.ts"
+    models: "ModelName.model.ts"
+    tests: "filename.test.ts"
+  
+  prefixes_suffixes:
+    interfaces: "I"                # IUserService
+    abstract_classes: "Abstract"  # AbstractRepository
+    test_functions: "test_"       # test_user_creation
+    private_methods: "_"          # _validateInput
+```
+
+**Auto-Applied**:
+- Backend Developer generates class: `UserService` (PascalCase)
+- Backend Developer generates table: `users` (snake_case)
+- Frontend Developer generates endpoint call: `/api/v1/user-profiles` (kebab-case)
+
+### 2. Design Patterns
+
+**Purpose**: Mandate architectural patterns as implementation constraints
+
+**Decisions Stocked**:
+```yaml
+design_patterns:
+  data_access: repository_pattern
+  service_layer: service_classes
+  dependency_injection: constructor_injection
+  validation: dto_validation
+  cqrs: false
+  event_sourcing: false
+  domain_driven_design: false
+  
+  service_specific_patterns:
+    - service: order-service
+      pattern: CQRS
+      rationale: "High read/write volume requires separate models"
+```
+
+**Auto-Applied**:
+- Backend Developer MUST use Repository pattern for all data access
+- Backend Developer MUST use constructor injection for dependencies
+- order-service specifically MUST implement CQRS (separate read/write models)
+
+### 3. Error & Response Standards
+
+**Purpose**: Standardize all API error responses and success envelopes
+
+**Decisions Stocked**:
+```yaml
+error_response_standards:
+  error_code_mapping:
+    validation_error: 400
+    authentication_error: 401
+    authorization_error: 403
+    not_found_error: 404
+    conflict_error: 409
+    internal_error: 500
+  
+  response_envelope:
+    success_format: '{"data": {}, "meta": {"request_id": "", "timestamp": ""}}'
+    error_format: '{"error": {"code": "", "message": "", "details": []}, "meta": {"request_id": "", "timestamp": ""}}'
+    include_request_id: true
+    include_timestamp: true
+  
+  error_detail_level: standard
+```
+
+**Auto-Applied**:
+- Backend Developer returns: `{"data": {...}, "meta": {"request_id": "abc123", "timestamp": "2024-01-15T10:30:00Z"}}`
+- Backend Developer returns 400 for validation errors, 401 for auth errors, etc.
+- Frontend Developer expects: `response.data` for success, `response.error` for errors
+
+### 4. Observability Standards
+
+**Purpose**: Standardize logging, tracing, and metrics across all services
+
+**Decisions Stocked**:
+```yaml
+observability_standards:
+  logging:
+    levels: [DEBUG, INFO, WARN, ERROR]
+    structured_logging: true
+    mandatory_fields: [trace_id, correlation_id, service_name, timestamp, level]
+    sensitive_data_masking: true
+  
+  tracing:
+    trace_id_header: X-Trace-ID
+    correlation_id_header: X-Correlation-ID
+    span_naming_format: "service.operation"
+  
+  metrics:
+    naming_format: "service_name_metric_name_unit"
+    mandatory_labels: [service, environment, version]
+    latency_buckets: [0.01, 0.05, 0.1, 0.5, 1, 5, 10]
+```
+
+**Auto-Applied**:
+- Backend Developer logs: `{"trace_id": "...", "correlation_id": "...", "service_name": "order-service", "timestamp": "...", "level": "INFO", "message": "..."}`
+- DevOps Engineer configures: `X-Trace-ID` and `X-Correlation-ID` headers in all services
+- DevOps Engineer creates metrics: `order_service_requests_total`, `auth_service_latency_seconds`
+
+## CLI Commands
+
+### Stock All Decisions (Recommended - One-Time Setup)
+
+```bash
+dhurandhar decisions --stock
+```
+
+**Interactive Setup**:
+```
+📦 Stock All Technical Decisions
+
+1/4: Naming Conventions
+? Class naming style: PascalCase
+? Function naming style: camelCase
+? Database table naming: snake_case
+? API endpoint naming: kebab-case
+
+2/4: Design Patterns
+? Data access pattern: repository_pattern
+? Dependency injection: constructor_injection
+? Validation strategy: dto_validation
+
+3/4: Error Standards
+? Error response format: Standard Envelope
+? Include request_id: yes
+? Include timestamp: yes
+
+4/4: Observability Standards
+? Structured JSON logging: yes
+? Trace ID header: X-Trace-ID
+? Correlation ID header: X-Correlation-ID
+
+✓ All decisions stocked
+
+These standards will be:
+  - Automatically applied to all new code
+  - Enforced by drift detection
+  - Used as constraints by implementation personas
+```
+
+### Show Registered Decisions
+
+```bash
+dhurandhar decisions --show
+```
+
+**Output**:
+```
+📋 Technical Decision Registry
+
+Naming Conventions:
+  Case Styles:
+    classes: PascalCase
+    functions: camelCase
+    database_tables: snake_case
+    api_endpoints: kebab-case
+  File Patterns:
+    components: ComponentName.tsx
+    services: ServiceName.service.ts
+
+Design Patterns:
+  data_access: repository_pattern
+  dependency_injection: constructor_injection
+  validation: dto_validation
+
+Error Response Standards:
+  HTTP Status Mapping:
+    validation_error: 400
+    authentication_error: 401
+    not_found_error: 404
+  Response Envelope:
+    Success: {"data": {}, "meta": {...}}
+    Error: {"error": {...}, "meta": {...}}
+
+Observability Standards:
+  Logging:
+    Structured: yes
+    Mandatory Fields: trace_id, correlation_id, service_name
+  Tracing:
+    Trace ID Header: X-Trace-ID
+```
+
+### Set Individual Decision Category
+
+```bash
+dhurandhar decisions --set naming
+dhurandhar decisions --set patterns
+dhurandhar decisions --set errors
+dhurandhar decisions --set observability
+```
+
+## Integration with Workflow
+
+### During Install
+
+```bash
+dhurandhar install
+
+? Project identifier: my-platform
+? Architecture: microservices
+? Primary language: go
+
+? Stock technical decisions now? yes
+
+[Runs: dhurandhar decisions --stock]
+
+✓ Framework installed
+✓ Decisions stocked
+```
+
+### During Service Add
+
+```bash
+dhurandhar service add "user: User management"
+
+[Reads decision_registry]
+→ classes: PascalCase
+→ data_access: repository_pattern
+→ error_envelope: {"data": {}, "meta": {}}
+
+[Generates service with constraints]
+✓ user-service added
+✓ Decision constraints applied:
+  - Classes: PascalCase (UserService, UserRepository)
+  - Pattern: Repository pattern enforced
+  - Errors: Standard envelope format
+
+[Delegates to Backend Developer with IMMUTABLE constraints]
+```
+
+### Implementation Layer Receives Constraints
+
+**Backend Developer**:
+```yaml
+# Received from decision_registry (IMMUTABLE)
+constraints:
+  naming:
+    classes: PascalCase
+    functions: camelCase
+  patterns:
+    data_access: repository_pattern
+    dependency_injection: constructor_injection
+  errors:
+    envelope: '{"data": {}, "meta": {}}'
+  logging:
+    mandatory_fields: [trace_id, service_name, timestamp]
+```
+
+**Backend Developer MUST**:
+- Name classes: `UserService`, `OrderRepository` (PascalCase)
+- Implement Repository pattern: `UserRepository.findById()`
+- Use constructor injection: `constructor(userRepo: UserRepository)`
+- Return errors: `{"error": {...}, "meta": {...}}`
+- Log with: `{trace_id, service_name, timestamp, ...}`
+
+**NO DEVIATION. These are architectural constraints.**
+
+## Benefits
+
+### 1. Zero Repeated Decisions
+
+**Before**: Every developer asks "PascalCase or snake_case?" (50+ times/project)
+**After**: Asked once during `decisions --stock`, never again
+
+### 2. Immediate Onboarding
+
+New developer:
+```bash
+dhurandhar decisions --show
+```
+"Ah, we use PascalCase for classes, Repository pattern for data access, standard error envelope. Got it."
+
+### 3. Automatic Enforcement
+
+System Observer detects:
+```
+Code: class user_service (snake_case)
+Decision: classes = PascalCase
+
+Violation: user_service should be UserService
+```
+
+### 4. Implementation Consistency
+
+All Backend Developers use same patterns.
+All APIs use same error format.
+All logs have same structure.
+
+**100% consistency across codebase.**
+
+---
+
+**Dhurandhar v2.5: Stock Decisions Once, Apply Everywhere**