s9n-devops-agent 1.0.0

package/docs/houserules.md

@@ -0,0 +1,267 @@
+# Claude House Rules for CS_DevOpsAgent
+
+## Testing Policy (Required)
+
+Goal: Every bug fix and feature ships with an executable test.
+
+Location: test_cases/<area>/<component>/.
+
+DoD: (1) failing test reproduces bug (red), (2) fix makes it pass (green), (3) tests wired into CI and local runner.
+
+Naming: YYYYMMDD_<short-slug>_spec.(py|ts|js|go|rb|java)
+
+Non-duplication: Extend existing tests for the same bug.
+
+Determinism: No flaky/random tests; use seeds and fake timers.
+
+## Test Generation Rules (for Claude / code assistants)
+
+Always write the failing test first.
+
+Infer <area>/<component> from changed paths.
+
+Stub external services; avoid real I/O unless explicitly needed.
+
+Use native runners per language (pytest, vitest/jest, go test, rspec, JUnit).
+
+Add short "why it failed before the fix" note in the test.
+
+## Test Case Template
+```
+# Test Case: <human title>
+- Area: <e.g., worktree>
+- Component: <e.g., manager>
+- Related Issue/PR: <#id or link>
+- Repro Summary: <steps/inputs>
+- Expected Behavior: <should happen>
+- Regression Guard: <what breaks if it fails again>
+```
+
+<code block with the actual test file content>
+
+## Partial Test Execution (Targeted Runs)
+
+By default, local runs and CI only execute tests for changed areas (files in the PR/branch).
+
+Areas are inferred from changed file paths and mapped to test_cases/<area>/<component> directories.
+
+If we can't infer a mapping, we fallback to full suite.
+
+You can override the scope:
+
+scripts/run-tests --all → full suite
+
+scripts/run-tests --changed → only changed areas (default)
+
+scripts/run-tests test_cases/<area>/<component> → specific folder
+
+## Logging Policy
+
+All test scripts log with UTC timestamps, levels (INFO/WARN/ERROR/DEBUG), and grouping for CI.
+
+Set LOG_LEVEL to debug|info|warn|error (default info).
+
+Enable deep tracing with TRACE=1 (verbose commands, environment, and selection decisions).
+
+## Auto-Run on Bugfix Workflow
+
+If the current branch name or latest commit message contains fix: or bug:, targeted tests for the affected areas run first; if they pass, we run the rest of that language's suite.
+
+CI blocks merge if: tests fail or a bugfix PR lacks an associated test.
+
+## Code Style Guidelines for CS_DevOpsAgent
+
+### Comment Style
+- Use descriptive header comments for major sections
+- Include purpose and key features at the top of files
+- Document complex logic inline
+- Keep comments concise but informative
+
+### Module Structure
+- Group related functionality together
+- Use clear section separators
+- Export modules properly for reuse
+- Maintain consistent naming conventions
+
+### Error Handling
+- Always handle errors gracefully
+- Log errors with appropriate levels
+- Provide useful error messages
+- Clean up resources on failure
+
+### Worktree Management Specifics
+- Always check if running in CS_DevOpsAgent repo itself
+- Detect agent from environment variables
+- Create isolated worktrees per agent
+- Maintain agent configuration files
+- Handle branch naming consistently
+
+## Usage Examples
+
+Run only changed areas (default):
+```bash
+scripts/run-tests --changed
+```
+
+Force full suite:
+```bash
+scripts/run-tests --all
+```
+
+Force a folder (e.g., during triage):
+```bash
+scripts/run-tests test_cases/worktree/manager
+```
+
+Increase logs:
+```bash
+LOG_LEVEL=debug scripts/run-tests --changed
+TRACE=1 scripts/run-tests --changed
+```
+
+## Infrastructure Documentation Policy (NEW)
+
+### Purpose
+Track all infrastructure changes in a centralized location for team visibility and compliance.
+
+### Location
+`/Documentation/infrastructure.md` - Created automatically if it doesn't exist.
+
+### What to Document
+- **Configuration Changes**: Environment variables, settings files, config updates
+- **Dependency Updates**: New packages, version changes, removals
+- **Build System Changes**: Scripts, build configs, CI/CD updates
+- **Architecture Changes**: New services, components, integrations
+- **Database Changes**: Schema updates, migrations, indexes
+- **API Changes**: Endpoints, authentication, rate limits
+- **Security Changes**: Auth updates, certificates, permissions
+
+### Format
+```markdown
+## [Date] - [Agent/Developer Name]
+### Category: [Config|Dependencies|Build|Architecture|Database|API|Security]
+**Change Type**: [Added|Modified|Removed|Fixed]
+**Component**: [Affected component/service]
+**Description**: Brief description of the change
+**Reason**: Why this change was necessary
+**Impact**: Potential impacts or considerations
+**Files Changed**: 
+- file1.js
+- config/settings.json
+```
+
+### Auto-Detection Rules
+1. Monitor for changes in:
+   - `package.json`, `package-lock.json`
+   - `.env`, `.env.*` files
+   - `*config*.js`, `*config*.json`
+   - `Dockerfile`, `docker-compose.yml`
+   - `.github/workflows/*`
+   - Database migration files
+   - API route definitions
+
+2. Auto-generate entry when detected
+3. Include in commit message: `infra:` prefix when infrastructure changes detected
+
+### Commit Message Enhancement
+When infrastructure changes are detected:
+```
+infra(category): description
+
+- Updated /Documentation/infrastructure.md
+- [List of infrastructure changes]
+```
+
+Example:
+```
+infra(deps): add worktree management dependencies
+
+- Updated /Documentation/infrastructure.md
+- Added chokidar@3.5.3 for file watching
+- Added execa@6.1.0 for process management
+- Modified package.json scripts
+```
+
+## Environment Variables for Worktree Management
+
+- `AGENT_NAME` or `AI_AGENT`: Identifies the AI agent
+- `AGENT_TASK` or `AI_TASK`: Task or feature being worked on
+- `AC_USE_WORKTREE`: Enable/disable worktree creation (true/false/auto)
+- `AC_MSG_FILE`: Path to agent-specific commit message file
+- `AC_BRANCH_PREFIX`: Prefix for agent branches
+- `AC_TRACK_INFRA`: Enable infrastructure tracking (default: true)
+- `AC_INFRA_DOC_PATH`: Path to infrastructure doc (default: /Documentation/infrastructure.md)
+
+---
+
+## Prep TODO & Coordination (Multi-Agent Handshake)
+
+**Purpose:** Prevent agents from stepping on each other by publishing an _edit plan_ before changing files. The commit agent reads these plans, reserves shards (coarse path buckets), and either **acknowledges** or **blocks** the work.
+
+### Agent Workflow
+
+**Agents MUST write** a single JSON at `.ac-prep/<agent>.json` **before** edits and wait for `.ac/ack/<agent>.json`.
+
+### Prep JSON Format
+```json
+{
+  "agent": "<agent-id>",
+  "task": "<short-slug>",
+  "branch": "<target-branch>",
+  "paths": ["<glob1>", "<glob2>"],
+  "shards": ["<shard1>", "<shard2>"],
+  "reason": "<why>",
+  "priority": 1-10,
+  "createdAt": "<ISO-8601>",
+  "ttlMs": 600000
+}
+```
+
+### Flow
+
+1. **Write prep file** → `.ac-prep/<agent>.json`
+2. **Wait for acknowledgment** → `.ac/ack/<agent>.json`
+3. **Check status**:
+   - `status:"ok"` → proceed only within acknowledged paths/shards
+   - `status:"blocked"` → do not edit; narrow scope or wait; re-publish
+   - `status:"queued"` → wait for turn based on priority
+4. **After edits** → write `.claude-commit-msg` (Conventional Commit + 1–3 bullets)
+5. **If alert appears** → `.git/.ac/alerts/<agent>.md` → re-run with narrower scope
+
+### Shard System
+
+Shards live in `.ac-shards.json`. The commit agent:
+- **Reserves shards** on prep, acks or blocks
+- **At commit**, claims shards and stages only owned files
+- **Overlapping work** is blocked/queued/branched per config
+- **Writes human alerts** to `.git/.ac/alerts/<agent>.md` when overlap occurs
+
+### Priority Levels
+- `10`: Critical hotfix
+- `7-9`: High priority features
+- `4-6`: Normal development
+- `1-3`: Low priority/cleanup
+
+### Conflict Resolution Strategy
+```
+AC_SHARD_STRATEGY options:
+- "block": Prevent overlapping edits (default)
+- "branch": Create agent-specific branches
+- "queue": Queue based on priority and timestamp
+```
+
+### Agent Identification
+Agents are identified by:
+- Environment variable: `AGENT_NAME` or `AI_AGENT`
+- Auto-detection from API keys (Claude, Copilot, Cursor, etc.)
+- Session-based: `session-${USER}@${HOSTNAME}`
+
+### Monitoring
+Check coordination status:
+```bash
+ls -la .ac-prep/      # Pending prep requests
+ls -la .ac/ack/       # Acknowledgments
+ls -la .git/.ac/alerts/  # Conflict alerts
+cat .git/.ac/claims/*.json  # Active claims
+```
+

package/docs/infrastructure.md

@@ -0,0 +1,68 @@
+# Infrastructure Change Log
+
+This document tracks all infrastructure changes made to the project. It is automatically updated when infrastructure-related files are modified.
+
+## Format Guidelines
+
+Each entry should follow this format:
+```
+## [Date] - [Agent/Developer Name]
+### Category: [Config|Dependencies|Build|Architecture|Database|API|Security]
+**Change Type**: [Added|Modified|Removed|Fixed]
+**Component**: [Affected component/service]
+**Description**: Brief description of the change
+**Reason**: Why this change was necessary
+**Impact**: Potential impacts or considerations
+**Files Changed**: 
+- file1.js
+- config/settings.json
+```
+
+---
+
+## 2025-01-28 - System
+
+### Category: Architecture
+**Change Type**: Added
+**Component**: CS_DevOpsAgent
+**Description**: Initial infrastructure documentation setup
+**Reason**: Establish centralized tracking of infrastructure changes
+**Impact**: All future infrastructure changes will be logged here
+**Files Changed**: 
+- Documentation/infrastructure.md (created)
+- claude.md (updated with infrastructure policy)
+
+---
+
+## 2025-01-28 - System
+
+### Category: Dependencies
+**Change Type**: Added
+**Component**: CS_DevOpsAgent Testing
+**Description**: Added test infrastructure and logging libraries
+**Reason**: Enable comprehensive testing with targeted execution
+**Impact**: Improved test coverage and CI/CD integration
+**Files Changed**: 
+- scripts/lib/log.sh
+- scripts/changed-areas.sh
+- scripts/run-tests
+- test_cases/* (structure created)
+
+---
+
+## 2025-01-28 - System
+
+### Category: Architecture
+**Change Type**: Added
+**Component**: Worktree Management
+**Description**: Implemented multi-agent worktree management system
+**Reason**: Enable parallel development by multiple AI agents
+**Impact**: Agents can now work simultaneously without conflicts
+**Files Changed**: 
+- worktree-manager.js
+- run-with-agent.js
+- cs-devops-agent-worker.js (enhanced with worktree detection)
+
+---
+
+<!-- New entries will be added above this line -->

package/docs/testing-guide.md

@@ -0,0 +1,224 @@
+# Multi-Agent Coordination Testing Guide
+
+**Date:** September 28, 2025  
+**Version:** 1.0  
+**Author:** SecondBrain AI
+
+---
+
+## 🎯 Overview
+
+This guide documents how to test and validate the multi-agent coordination system in CS_DevOpsAgent. The system prevents conflicts when multiple AI agents (Claude, Copilot, Cursor, Warp, etc.) work on the same codebase simultaneously.
+
+## 🧪 Test Scripts Available
+
+### 1. Simple Coordination Test
+**File:** `test-coordination-simple.sh`  
+**Purpose:** Quick validation of coordination system setup and basic functionality
+
+```bash
+./test-coordination-simple.sh
+```
+
+**What it tests:**
+- ✅ Coordination directories exist
+- ✅ Configuration files present
+- ✅ Agent prep requests can be created
+- ✅ Multiple agents can request concurrently
+- ✅ Monitoring capabilities
+
+### 2. Comprehensive Test Suite
+**File:** `test-coordination.sh`  
+**Purpose:** Full test suite with isolated environment
+
+```bash
+./test-coordination.sh
+```
+
+**What it tests:**
+- Setup script idempotency
+- Directory structure creation
+- JSON template generation
+- Priority ordering
+- Shard reservation system
+- Expiration handling
+
+### 3. Multi-Agent Simulation
+**File:** `simulate-multi-agents.sh`  
+**Purpose:** Simulates multiple agents working concurrently in separate processes
+
+```bash
+./simulate-multi-agents.sh
+```
+
+**Features:**
+- Simulates 4 different agents (Claude, Copilot, Cursor, Warp)
+- Each agent runs in a separate background process
+- Real-time monitoring dashboard
+- Conflict detection simulation
+- Generates comprehensive report
+
+## 📊 Test Results Interpretation
+
+### Success Indicators
+- ✅ All prep requests created successfully
+- ✅ No file conflicts between agents
+- ✅ Proper priority ordering maintained
+- ✅ Monitoring shows accurate status
+
+### Warning Signs
+- ⚠️ Alerts generated in `.git/.ac/alerts/`
+- ⚠️ Blocked acknowledgments
+- ⚠️ Expired requests not cleaned up
+- ⚠️ Missing configuration files
+
+## 🔧 Manual Testing Scenarios
+
+### Scenario 1: Two Agents, Same Shard
+Simulate Claude and Copilot trying to edit the same service files:
+
+```bash
+# Terminal 1 - Claude
+export AGENT_NAME="claude"
+./agent-prep.sh "auth-service" "src/services/**" 6
+
+# Terminal 2 - Copilot (run immediately after)
+export AGENT_NAME="copilot"
+./agent-prep.sh "api-update" "src/services/**" 7
+
+# Check for conflicts
+ls -la .git/.ac/alerts/
+```
+
+### Scenario 2: Priority Queue Test
+Test that high-priority requests are processed first:
+
+```bash
+# Low priority request
+export AGENT_NAME="agent1"
+./agent-prep.sh "cleanup" "docs/**" 2
+
+# High priority request
+export AGENT_NAME="agent2"
+./agent-prep.sh "hotfix" "src/core/**" 10
+
+# Monitor processing order
+./monitor-agents.sh
+```
+
+### Scenario 3: Concurrent Non-Conflicting Work
+Test multiple agents working on different shards:
+
+```bash
+# Each in a separate terminal
+export AGENT_NAME="claude" && ./agent-prep.sh "docs-update" "docs/**" 5
+export AGENT_NAME="copilot" && ./agent-prep.sh "test-suite" "tests/**" 5
+export AGENT_NAME="cursor" && ./agent-prep.sh "config-update" "config/**" 5
+```
+
+## 🔍 Monitoring During Tests
+
+### Real-Time Status
+```bash
+# Watch active requests
+watch -n 2 'ls -la .ac-prep/*.json | grep -v template'
+
+# Monitor acknowledgments
+watch -n 2 'ls -la .ac/ack/*.json | grep -v template'
+
+# Check for alerts
+watch -n 2 'ls -la .git/.ac/alerts/'
+```
+
+### Using the Monitor Script
+```bash
+./monitor-agents.sh
+```
+
+Shows:
+- Active prep requests with priorities
+- Current acknowledgments
+- Any conflict alerts
+- Processing queue status
+
+## 🐛 Troubleshooting Test Issues
+
+### Issue: Tests fail with "command not found"
+**Solution:** Ensure setup script has been run:
+```bash
+./setup-prep-handshake.sh
+```
+
+### Issue: "Permission denied" errors
+**Solution:** Make scripts executable:
+```bash
+chmod +x *.sh
+```
+
+### Issue: JSON parsing errors
+**Solution:** Install jq for better JSON handling:
+```bash
+brew install jq  # macOS
+```
+
+### Issue: Simulation hangs
+**Solution:** Kill background processes:
+```bash
+pkill -f agent-prep
+rm -rf /tmp/multi-agent-sim-*
+```
+
+## 📈 Performance Benchmarks
+
+Expected timings for a healthy system:
+- Prep request creation: < 100ms
+- Acknowledgment generation: < 200ms
+- Conflict detection: < 500ms
+- Full simulation (4 agents): ~30 seconds
+
+## 🔄 Continuous Testing
+
+### Pre-Commit Hook
+Add to `.git/hooks/pre-commit`:
+```bash
+#!/bin/bash
+./test-coordination-simple.sh
+```
+
+### CI/CD Integration
+For GitHub Actions:
+```yaml
+- name: Test Multi-Agent Coordination
+  run: |
+    ./setup-prep-handshake.sh
+    ./test-coordination-simple.sh
+```
+
+## 📝 Test Coverage
+
+Current test coverage:
+- ✅ Basic setup validation: 100%
+- ✅ Request creation: 100%
+- ✅ Concurrent requests: 90%
+- ⚠️ Conflict resolution: 70%
+- ⚠️ Expiration handling: 60%
+- 🔄 Real-time coordination: In progress
+
+## 🚀 Next Steps
+
+To improve testing:
+1. Add automated conflict resolution tests
+2. Implement deadline expiration tests
+3. Add stress testing (10+ concurrent agents)
+4. Create integration tests with actual Git operations
+5. Add performance regression tests
+
+## 📚 Related Documentation
+
+- [Multi-Agent Coordination Update Notes](../Update%20Notes/2025-09-28-multi-agent-coordination.md)
+- [House Rules](../houserules.md)
+- [README](../README.md#-multi-agent-coordination)
+
+---
+
+**Note:** Always run tests in a clean environment to ensure accurate results. The coordination system is designed to be idempotent, so running setup multiple times should not cause issues.

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "s9n-devops-agent",
+  "version": "1.0.0",
+  "description": "CS_DevOpsAgent - Intelligent Git Automation System with multi-agent support and session management",
+  "type": "module",
+  "main": "src/cs-devops-agent-worker.js",
+  "bin": {
+    "s9n-devops-agent": "./bin/cs-devops-agent"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "docs/",
+    "start-devops-session.sh",
+    "cleanup-sessions.sh",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "./start-devops-session.sh",
+    "dev": "./start-devops-session.sh",
+    "devops": "./start-devops-session.sh",
+    "devops:list": "node src/session-coordinator.js list",
+    "devops:start": "node src/session-coordinator.js start",
+    "devops:close": "node src/close-session.js",
+    "devops:cleanup": "./cleanup-sessions.sh",
+    "setup": "node src/setup-cs-devops-agent.js",
+    "test": "jest test_cases/",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:worktree": "jest test_cases/worktree/",
+    "test:e2e": "./test_scripts/test-multi-agent-e2e.sh",
+    "test:push-behind": "jest test_scripts/push_behind_spec.js",
+    "test:debug": "./debug-failing-tests.sh"
+  },
+  "keywords": [
+    "git",
+    "automation",
+    "commit",
+    "workflow",
+    "vscode",
+    "branching",
+    "development-tools"
+  ],
+  "author": "Sachin Dev Duggal",
+  "license": "MIT",
+  "dependencies": {
+    "chokidar": "^3.5.3",
+    "execa": "^7.1.1"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SecondBrainAICo/CS_DevOpsAgent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SecondBrainAICo/CS_DevOpsAgent/issues"
+  },
+  "homepage": "https://github.com/SecondBrainAICo/CS_DevOpsAgent#readme"
+}