dhurandhar 1.0.0

package/.dhurandhar-session-start.md

@@ -0,0 +1,242 @@
+# Dhurandhar Session Start Protocol
+
+## System Observer - Primary Rehydration Persona
+
+When starting a new session with Dhurandhar, the **System Observer** is ALWAYS invoked first.
+
+## Session Start Sequence
+
+```
+1. System Observer loads SYSTEM_DESIGN_MAP.yaml
+2. Performs silent background audit
+3. Generates context summary
+4. Checks drift percentage
+5. Provides context to other personas
+6. Reports to user (if drift > 25%)
+```
+
+## Automatic Rehydration Report
+
+### Format
+
+```markdown
+[System Observer] Session Rehydrated
+
+Project: [name]
+Architecture: [type]
+Last Updated: [timestamp]
+
+Active Strategies:
+  Persistence: [model]
+  Communication: [pattern]
+  Security: [auth_type]
+  Resilience: [circuit_breaker status]
+
+Architecture Status:
+  Services: [X]/[Y] implemented
+  Entities: [X]/[Y] implemented
+  Stories: [X]/[Y] tested
+  Strategy Compliance: [XX]%
+
+Drift: [X]%
+[If drift > 25%: ⚠ Significant drift detected. Run: dhurandhar audit --summary]
+
+Definition of Done:
+  EPIC-001: [XX]% ([X]/[Y] stories complete)
+  EPIC-002: [XX]% ([X]/[Y] stories complete)
+
+Ready. What's next?
+```
+
+## Example Rehydration (Healthy System)
+
+```
+[System Observer] Session Rehydrated
+
+Project: ecommerce-platform
+Architecture: microservices
+Last Updated: 2024-01-15T10:30:00Z
+
+Active Strategies:
+  Persistence: database_per_service
+  Communication: asynchronous_events (kafka)
+  Security: jwt_centralized
+  Resilience: Circuit breaker enabled
+
+Architecture Status:
+  Services: 5/5 implemented
+  Entities: 8/8 implemented
+  Stories: 12/12 tested
+  Strategy Compliance: 100%
+
+Drift: 0%
+
+Definition of Done:
+  EPIC-001 (User Authentication): 100% (5/5 stories complete)
+  EPIC-002 (Order Processing): 100% (7/7 stories complete)
+
+Ready. What's next?
+```
+
+## Example Rehydration (Drift Detected)
+
+```
+[System Observer] Session Rehydrated
+
+Project: my-platform
+Architecture: microservices
+Last Updated: 2024-01-14T15:45:00Z
+
+Active Strategies:
+  Persistence: database_per_service
+  Communication: asynchronous_events (kafka)
+  Security: jwt_centralized
+
+Architecture Status:
+  Services: 3/5 implemented
+  Entities: 6/8 implemented
+  Stories: 8/12 tested
+  Strategy Compliance: 80%
+
+Drift: 32%
+
+⚠ Significant architectural drift detected
+
+Unimplemented:
+  - order-service (defined in SDM)
+  - payment-service (defined in SDM)
+  - STORY-005, STORY-008, STORY-011, STORY-012 (tests not generated)
+
+Strategy Violations:
+  - user-service: Missing event boundaries (event-driven strategy)
+
+Run for details:
+  dhurandhar audit --drift
+
+Definition of Done:
+  EPIC-001 (Authentication): 80% (4/5 stories complete)
+  EPIC-002 (Orders): 57% (4/7 stories complete)
+
+What's next?
+```
+
+## Silent Mode (drift < 25%)
+
+If drift is acceptable, System Observer provides minimal context:
+
+```
+[System Observer] Session Ready
+
+5 services, 8 entities, 12 stories (all tested)
+Strategy Compliance: 95%
+Drift: 8%
+
+Context loaded. What's next?
+```
+
+## Integration with AI IDEs
+
+### For Cursor/Claude/Augment
+
+1. **Place this file** (`.dhurandhar-session-start.md`) in project root
+2. **Agent initialization**: Read this file + `SYSTEM_DESIGN_MAP.yaml`
+3. **System Observer mode**: Perform audit automatically
+4. **Report to user**: Show rehydration status
+5. **Ready state**: Wait for user command
+
+### Example AI Agent Prompt
+
+```
+You are working on a Dhurandhar-managed project.
+
+FIRST: Assume System Observer persona
+1. Read SYSTEM_DESIGN_MAP.yaml
+2. Perform audit (check services, entities, stories exist in code)
+3. Calculate drift percentage
+4. Report rehydration status to user
+
+THEN: Switch to appropriate persona based on user command:
+- service/entity/strategy → Lead System Architect
+- epic/story/test → Test Architect
+- audit/context → System Observer
+- edge-cases → Edge Case Hunter
+
+Always start with System Observer rehydration.
+```
+
+## Rehydration Data Structure
+
+The System Observer provides this context to other personas:
+
+```javascript
+{
+  project: {
+    name: "ecommerce-platform",
+    architecture: "microservices",
+    lastUpdated: "2024-01-15T10:30:00Z"
+  },
+  
+  strategies: {
+    persistence: { model: "database_per_service" },
+    communication: { 
+      primary_pattern: "asynchronous_events",
+      event_bus: { technology: "kafka" }
+    },
+    security: { authentication: "jwt_centralized" },
+    resilience: { circuit_breaker: true }
+  },
+  
+  architecture: {
+    services: {
+      total: 5,
+      implemented: 5,
+      list: ["auth-service", "user-service", "order-service", "payment-service", "inventory-service"]
+    },
+    entities: {
+      total: 8,
+      implemented: 8,
+      list: ["User", "Session", "Order", "OrderItem", "Payment", "Product", "Inventory", "Review"]
+    },
+    stories: {
+      total: 12,
+      tested: 12,
+      coverage: 100
+    }
+  },
+  
+  drift: {
+    percentage: 0,
+    unimplemented: [],
+    unmanaged: [],
+    violations: []
+  },
+  
+  definitionOfDone: {
+    epics: [
+      { id: "EPIC-001", name: "User Authentication", progress: 100, stories: "5/5" },
+      { id: "EPIC-002", name: "Order Processing", progress: 100, stories: "7/7" }
+    ]
+  }
+}
+```
+
+## Commands After Rehydration
+
+Once rehydrated, System Observer hands off to appropriate personas:
+
+| User Command | Persona | Context Used |
+|--------------|---------|--------------|
+| "Add payment service" | Lead System Architect | Uses strategies, existing services |
+| "Create login story" | Test Architect | Uses agile_blueprint, services |
+| "Check drift" | System Observer | Uses audit data from rehydration |
+| "Add edge cases for STORY-003" | Edge Case Hunter | Uses story definition, strategies |
+
+## Remember
+
+- **System Observer is ALWAYS first** on session start
+- **Silent if drift < 25%** (brief summary only)
+- **Alert if drift >= 25%** (show details, recommend audit)
+- **Provide context to all personas** (strategies, architecture, drift)
+- **Definition of Done** is immediately available (no recalculation needed)
+
+This ensures every session starts with a truthful view of the system state.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Dhurandhar Project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,416 @@
+# Dhurandhar
+
+**Engineering-First + Test-First + Strategy-Driven + Decision-Stocked Framework** - Bmad-level maturity with zero cognitive fatigue
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
+
+## Philosophy
+
+Dhurandhar eliminates **architectural drift** and **cognitive fatigue** through:
+
+1. **Engineering-First**: Technical specifications over business justifications
+2. **Test-First**: Contract tests before implementation
+3. **Strategy-Driven**: Pluggable architectural patterns with global constraints
+4. **Decision-Stocked** (NEW v2.5): Stock all technical decisions ONCE, apply everywhere automatically
+5. **Drift Detection**: Automatic alignment between intent (SDM) and reality (code)
+6. **Direct Action**: 3-question limit per component, no justification loops
+7. **Persistent Context**: System Design Map (SDM) for cross-session rehydration
+
+**Stock decisions once. Set strategies once. All services follow. Tests define contracts. SDM stays in sync. No ceremony.**
+
+## Overview
+
+Dhurandhar integrates four powerful approaches:
+
+### Drift Detection Layer (NEW v2.3)
+- **System Observer**: Technical auditor persona (session gatekeeper)
+- **Automatic Drift Detection**: Compare SDM (intent) vs code (reality)
+- **Direct-Action Sync**: Update SDM to match codebase in seconds
+- **Evidence-Based Reports**: Only report verifiable facts
+- **Session Rehydration**: Instant context with drift assessment
+
+### Pluggable Strategies Layer (v2.2)
+- **Persistence Strategy**: Database-per-service, Shared DB, Event Sourcing
+- **Communication Pattern**: Event-driven, REST, gRPC, Hybrid
+- **State Management**: Distributed cache, Local cache, Sidecar
+- **Security**: JWT centralized, OAuth2, mTLS, API keys
+- **Resilience**: Circuit breaker, Retry policies, Timeouts
+- **Global Injection**: Set once, apply to all services automatically
+
+### Engineering-First Layer (v2.0)
+- **User Types**: Roles, permissions, authentication boundaries
+- **Entities & Relationships**: ERD-like database models
+- **Service Architecture**: Microservices with strategy-enhanced tech stacks
+- **Persistent State**: YAML-based architecture map
+
+### Test-First Agile Layer (v2.1)
+- **Epics**: High-level system capabilities
+- **Stories**: User journeys with API contracts
+- **Tasks**: Granular implementation steps with test coverage tracking
+- **Contract Tests**: Generated before implementation, strategy-aware
+
+## Key Features
+
+- **Technical Decision Registry** (NEW v2.5): Bmad-inspired "stock of decisions"
+  - Stock naming conventions, design patterns, error standards, observability ONCE
+  - Auto-apply to ALL code (never re-litigate basic conventions)
+  - Eliminate 98% of repeated technical debates
+  - Enforced as immutable constraints by implementation personas
+- **7-Persona Dhurandhar Council** (v2.4): Complete development lifecycle coverage
+  - **Audit Layer**: System Observer (drift detection, session gatekeeper)
+  - **Design Layer**: Lead System Architect (PRIMARY DECISION AUTHORITY)
+  - **Contract Layer**: Test Architect + Edge Case Hunter (tests, security)
+  - **Implementation Layer**: DevOps Engineer + Backend Developer + Frontend Developer
+- **Implementation Personas** (v2.4): Tool-agnostic infrastructure, backend, and frontend specialists
+- **Parallel Execution**: DevOps, Backend, Frontend work simultaneously from SDM
+- **Architectural Drift Detection** (v2.3): Automatic alignment between SDM and codebase
+- **Direct-Action Sync**: Update SDM to match code in seconds
+- **Pluggable Architectural Strategies** (v2.2): Set global patterns (7 categories)
+- **System Design Map (SDM)**: Persistent `SYSTEM_DESIGN_MAP.yaml` at project root
+- **Strategy Auto-Injection**: Services inherit architectural constraints automatically
+- **Contract-First Testing** (v2.1): Tests generated from API interaction boundaries
+- **Context Rehydration**: AI agents reload decisions + strategies + drift + tests instantly
+- **Direct-Action Pivots**: Change strategies without justification loops
+- **Definition of Done**: Track test coverage and implementation status
+- **Anti-Ceremony**: No business justifications, max 3 technical questions
+
+## Installation
+
+### Quick Install (NPX - Recommended)
+
+```bash
+npx dhurandhar install
+```
+
+**That's it!** No global installation needed.
+
+### Alternative: Global Installation
+
+```bash
+npm install -g dhurandhar
+dhurandhar install
+```
+
+See [INSTALLATION.md](INSTALLATION.md) for more options (local dependency, from source, etc.)
+
+---
+
+## Quick Start (15 Minutes)
+
+### Prerequisites
+
+- Node.js v20.0.0 or higher
+- npm >= 9.0.0
+
+### 1. Install Framework
+
+```bash
+# Using npx (recommended)
+npx dhurandhar install
+
+# OR using global install
+npm install -g dhurandhar
+dhurandhar install
+```
+
+**3 technical questions only**:
+1. Project identifier (kebab-case)
+2. Architecture type (microservices/monolith/serverless)
+3. Primary language (Go/TypeScript/Python/Rust/Java)
+
+### 2. Set Architectural Strategies (NEW - 5 minutes)
+
+```bash
+# Persistence: Database-per-Service
+dhurandhar strategy --set persistence
+
+# Communication: Event-Driven (Kafka)
+dhurandhar strategy --set communication
+
+# Security: JWT Centralized
+dhurandhar strategy --set security
+
+# Resilience: Circuit Breaker
+dhurandhar strategy --set resilience
+```
+
+**Result**: All future services will automatically inherit these constraints.
+
+### 3. Engineering-First: Define Architecture (Strategy Auto-Injection)
+
+```bash
+# Add service - strategies automatically applied!
+dhurandhar service add "auth: JWT authentication"
+
+# Result:
+# ✓ auth-service added: Go/Echo/PostgreSQL
+#   - Dedicated database: auth_db (db-per-service strategy)
+#   - Events: produces[user.authenticated] (event-driven strategy)
+#   - Auth: Self (jwt-centralized strategy)
+#   - Resilience: Circuit breaker enabled
+
+# Add entities
+dhurandhar entity add User
+dhurandhar entity add Session
+
+# Relate entities
+dhurandhar entity --relate  # Session → User
+```
+
+**Note**: Service automatically got dedicated DB, event boundaries, and circuit breaker from strategies!
+
+### 3. Test-First Agile: Define Requirements
+
+```bash
+# Add Epic (system capability)
+dhurandhar epic add "User Authentication & Authorization"
+
+# Add Story (user journey with API contract)
+dhurandhar story add "Email/Password Login" --epic EPIC-001
+```
+
+**Test Architect asks 3 technical questions**:
+1. Service? → auth-service
+2. Endpoint? → /api/v1/auth/login
+3. Method? → POST
+
+### 4. Generate Contract Tests
+
+```bash
+dhurandhar test --generate
+```
+
+**Output**:
+- `tests/contracts/story-001-standard.test.js` (happy path)
+- `tests/contracts/story-001-errors.test.js` (error states)
+- `tests/edge-cases/story-001-edge.test.js` (edge cases)
+
+### 5. Run Tests (Before Implementation)
+
+```bash
+npm install -D vitest
+npm test
+```
+
+**Expected**: All tests fail (no implementation yet). This is correct!
+
+### 6. Implement Services
+
+Implement `auth-service` to pass the contract tests.
+
+### 7. Run Tests (After Implementation)
+
+```bash
+npm test
+```
+
+**Expected**: All tests pass ✅
+
+### 8. Validate Coverage
+
+```bash
+dhurandhar test --validate
+```
+
+**Output**:
+```
+Coverage Report:
+  Total Stories: 1
+  Test Coverage: 100% (1/1)
+  Implementation: 100% (1/1)
+
+✓ Full coverage!
+```
+
+## Complete Workflow
+
+```bash
+# 1. Initialize
+dhurandhar install
+
+# 2. Define Architecture (Engineering-First)
+dhurandhar service add "auth: JWT auth"
+dhurandhar entity add User
+
+# 3. Define Requirements (Test-First Agile)
+dhurandhar epic add "User Authentication"
+dhurandhar story add "Login" --epic EPIC-001
+
+# 4. Generate Contract Tests
+dhurandhar test --generate
+
+# 5. Run tests → fail (expected)
+npm test
+
+# 6. Implement service to pass tests
+# (Implementation guided by contract tests)
+
+# 7. Run tests → pass
+npm test
+
+# 8. Validate
+dhurandhar test --validate
+
+# All state persists to SYSTEM_DESIGN_MAP.yaml
+```
+
+## System Design Map (SDM)
+
+The SDM is a YAML file at your project root: **`SYSTEM_DESIGN_MAP.yaml`**
+
+### Purpose
+
+- **Persistent Architecture State**: Survives across sessions
+- **Context Rehydration**: AI agents/developers read this first
+- **Single Source of Truth**: All architectural decisions in one place
+- **No Rediscovery**: Never repeat context gathering
+
+### Structure
+
+```yaml
+metadata:
+  project_name: my-system
+  architecture_type: microservices
+
+tech_stack:
+  languages: [Go, TypeScript]
+  frameworks: [Echo, React]
+  databases: [PostgreSQL, Redis]
+
+user_types:
+  - role: admin
+    permissions: [read:*, write:*]
+    authentication: jwt
+
+entities:
+  - name: User
+    attributes:
+      - name: id
+        type: uuid
+        constraints: [primary_key]
+    relationships:
+      - type: one_to_many
+        target: Post
+
+services:
+  - name: auth-service
+    scope: "JWT authentication"
+    tech_stack:
+      language: Go
+      framework: Echo
+      database: PostgreSQL
+    api:
+      type: rest
+      base_path: /api/v1/auth
+      port: 8080
+```
+
+## Project Structure
+
+```
+your-project/
+├── SYSTEM_DESIGN_MAP.yaml    # ← THE MOST IMPORTANT FILE
+├── .dhurandhar/
+│   ├── config.yaml
+│   └── modules/
+├── src/                       # Your code
+└── ...
+```
+
+## Creating a Design Module
+
+Create a new module by defining `module.yaml`:
+
+```yaml
+code: my-design
+name: "My System Design"
+version: "1.0.0"
+description: "A custom system design"
+
+dependencies:
+  - core
+
+design_components:
+  - name: frontend
+    type: application
+    properties:
+      framework: React
+
+  - name: backend
+    type: service
+    properties:
+      framework: Node.js
+
+relationships:
+  - from: frontend
+    to: backend
+    type: http_client
+
+build_processes:
+  - name: setup
+    steps:
+      - Install dependencies
+      - Configure environment
+```
+
+## Documentation
+
+- [Getting Started Guide](docs/getting-started.md)
+- [Module Development](docs/module-development.md)
+- [CLI Reference](docs/cli-reference.md)
+- [Configuration Guide](docs/configuration.md)
+- [API Documentation](docs/api.md)
+
+## Development
+
+### Running Tests
+
+```bash
+# Run unit tests
+npm test
+
+# Run integration tests
+npm run test:integration
+
+# Run all tests
+npm run test:all
+```
+
+### Code Quality
+
+```bash
+# Lint code
+npm run lint
+
+# Fix linting issues
+npm run lint:fix
+
+# Format code
+npm run format:fix
+
+# Check formatting
+npm run format:check
+```
+
+### Validation
+
+```bash
+# Validate configuration
+npm run validate:config
+
+# Validate modules
+npm run validate:modules
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Credits
+
+Inspired by best practices from Bmad-Method and modern system design frameworks.