s9n-devops-agent 1.2.1 → 1.3.1

package/src/house-rules-manager.js

@@ -0,0 +1,443 @@
+/**
+ * House Rules Version Manager
+ * ============================
+ * 
+ * Manages versioning and updates of DevOps Agent sections in house rules.
+ * Allows intelligent updates while preserving user customizations.
+ * 
+ * Each managed section includes:
+ * - Version marker: <!-- DEVOPS_AGENT_SECTION:name:version:checksum -->
+ * - Content checksum for change detection
+ * - End marker: <!-- END_DEVOPS_AGENT_SECTION:name -->
+ */
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Version of our house rules sections
+const HOUSERULES_VERSION = '1.3.0';
+
+// Managed sections with their content
+const MANAGED_SECTIONS = {
+  'file-coordination': {
+    version: '1.3.0',
+    title: '## 🚨 CRITICAL: File Coordination Protocol (MUST FOLLOW)',
+    content: `**IMPORTANT: Always check the house rules at the beginning of each session!**
+
+To prevent conflicts with other agents editing the same files, you MUST follow this protocol:
+
+### Before Editing ANY Files:
+
+1. **DECLARE YOUR INTENT FIRST**
+   Create a file at \`.file-coordination/active-edits/<your-name>-<session>.json\` with:
+   \`\`\`json
+   {
+     "agent": "<your-name>",
+     "session": "<session-id>",
+     "files": ["list", "of", "files", "you", "will", "edit"],
+     "operation": "edit",
+     "reason": "Brief description of what you're doing",
+     "declaredAt": "<current-ISO-8601-timestamp>",
+     "estimatedDuration": 300
+   }
+   \`\`\`
+
+2. **CHECK FOR CONFLICTS**
+   - Read ALL files in \`.file-coordination/active-edits/\`
+   - If ANY other agent has declared the same files, you must:
+     - WAIT for them to finish, OR
+     - Choose different files to edit
+
+3. **ONLY EDIT DECLARED FILES**
+   - Never edit files you haven't declared
+   - Stay within your declared scope
+
+4. **RELEASE WHEN DONE**
+   - Delete your declaration file after completing edits
+   - Or move it to \`.file-coordination/completed-edits/\`
+
+### If You Detect a Conflict:
+- DO NOT proceed with edits
+- Report the conflict to the user
+- Wait or choose alternative files
+
+        ### Helper Scripts Available:
+        - \`./scripts/coordination/check-file-availability.sh <files>\` - Check if files are available
+        - \`./scripts/coordination/declare-file-edits.sh <agent> <session> <files>\` - Declare your intent
+        - \`./scripts/coordination/release-file-edits.sh <agent> <session>\` - Release files after editing
+
+**This coordination prevents wasted work and merge conflicts!**`
+  },
+  'core-principles': {
+    version: '1.0.0',
+    title: '## Core Principles',
+    content: `1. **Always preserve existing functionality** - Never break working code
+2. **Follow existing patterns** - Match the codebase style and conventions
+3. **Communicate clearly** - Document your changes and reasoning
+4. **Coordinate with others** - Follow the file coordination protocol below`
+  },
+  'project-conventions': {
+    version: '1.0.0',
+    title: '## Project Conventions',
+    content: `### Code Style
+- Follow existing indentation and formatting patterns
+- Maintain consistent naming conventions used in the project
+- Keep functions small and focused
+- Write clear, descriptive variable and function names
+
+### Git Workflow
+- Write clear, descriptive commit messages
+- Follow conventional commit format when applicable (feat:, fix:, docs:, etc.)
+- Keep commits atomic and focused on a single change
+- Never commit sensitive information or credentials
+
+### Testing
+- Write tests for new functionality
+- Ensure existing tests pass before committing
+- Update tests when changing functionality
+
+### Documentation
+- Update README files when adding new features
+- Document complex logic with clear comments
+- Keep API documentation up to date
+- Update CHANGELOG for significant changes`
+  }
+};
+
+class HouseRulesManager {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot || process.cwd();
+    this.houseRulesPath = null;
+    this.findHouseRulesFile();
+  }
+
+  /**
+   * Find existing house rules file
+   */
+  findHouseRulesFile() {
+    const possiblePaths = [
+      'houserules.md',
+      'HOUSERULES.md',
+      '.github/HOUSERULES.md',
+      'docs/houserules.md',
+      'docs/HOUSERULES.md'
+    ];
+
+    for (const relativePath of possiblePaths) {
+      const fullPath = path.join(this.projectRoot, relativePath);
+      if (fs.existsSync(fullPath)) {
+        this.houseRulesPath = fullPath;
+        return fullPath;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Calculate checksum for content
+   */
+  calculateChecksum(content) {
+    return crypto.createHash('md5').update(content.trim()).digest('hex').substring(0, 8);
+  }
+
+  /**
+   * Create section marker
+   */
+  createSectionMarker(sectionName, version, checksum) {
+    return `<!-- DEVOPS_AGENT_SECTION:${sectionName}:${version}:${checksum} -->`;
+  }
+
+  /**
+   * Create end marker
+   */
+  createEndMarker(sectionName) {
+    return `<!-- END_DEVOPS_AGENT_SECTION:${sectionName} -->`;
+  }
+
+  /**
+   * Extract managed sections from existing house rules
+   */
+  extractManagedSections(content) {
+    const sections = {};
+    const pattern = /<!-- DEVOPS_AGENT_SECTION:(\w+[-\w]*):([0-9.]+):([a-f0-9]+) -->([\s\S]*?)<!-- END_DEVOPS_AGENT_SECTION:\1 -->/g;
+    
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      sections[match[1]] = {
+        name: match[1],
+        version: match[2],
+        checksum: match[3],
+        content: match[4].trim(),
+        startIndex: match.index,
+        endIndex: match.index + match[0].length
+      };
+    }
+    
+    return sections;
+  }
+
+  /**
+   * Check if a section needs updating
+   */
+  needsUpdate(sectionName, existingVersion, existingChecksum) {
+    const currentSection = MANAGED_SECTIONS[sectionName];
+    if (!currentSection) return false;
+
+    // Check version
+    if (this.compareVersions(currentSection.version, existingVersion) > 0) {
+      return true;
+    }
+
+    // Check checksum (in case we updated content without version bump)
+    const currentChecksum = this.calculateChecksum(currentSection.content);
+    return currentChecksum !== existingChecksum;
+  }
+
+  /**
+   * Compare semantic versions
+   */
+  compareVersions(v1, v2) {
+    const parts1 = v1.split('.').map(Number);
+    const parts2 = v2.split('.').map(Number);
+    
+    for (let i = 0; i < 3; i++) {
+      if (parts1[i] > parts2[i]) return 1;
+      if (parts1[i] < parts2[i]) return -1;
+    }
+    
+    return 0;
+  }
+
+  /**
+   * Format a managed section with markers
+   */
+  formatSection(sectionName) {
+    const section = MANAGED_SECTIONS[sectionName];
+    if (!section) return '';
+
+    const checksum = this.calculateChecksum(section.content);
+    const marker = this.createSectionMarker(sectionName, section.version, checksum);
+    const endMarker = this.createEndMarker(sectionName);
+
+    return `${marker}
+${section.title}
+
+${section.content}
+${endMarker}`;
+  }
+
+  /**
+   * Create new house rules with all managed sections
+   */
+  createNewHouseRules() {
+    const sections = [];
+    
+    // Header
+    sections.push(`# House Rules for AI Agents
+
+**IMPORTANT: All AI agents (Claude, Cline, Copilot, etc.) must read and follow these rules at the start of each session.**
+`);
+
+    // Add managed sections
+    sections.push(this.formatSection('file-coordination'));
+    sections.push('');
+    sections.push(this.formatSection('core-principles'));
+    sections.push('');
+    sections.push(this.formatSection('project-conventions'));
+
+    return sections.join('\n');
+  }
+
+  /**
+   * Update house rules intelligently
+   */
+  async updateHouseRules(options = {}) {
+    const { createIfMissing = true, backupExisting = true } = options;
+
+    // Find or create house rules file
+    if (!this.houseRulesPath) {
+      if (!createIfMissing) {
+        return { updated: false, reason: 'No house rules file found' };
+      }
+      
+      this.houseRulesPath = path.join(this.projectRoot, 'houserules.md');
+      const content = this.createNewHouseRules();
+      fs.writeFileSync(this.houseRulesPath, content);
+      
+      return { 
+        updated: true, 
+        created: true,
+        path: this.houseRulesPath,
+        sections: Object.keys(MANAGED_SECTIONS)
+      };
+    }
+
+    // Read existing content
+    const existingContent = fs.readFileSync(this.houseRulesPath, 'utf8');
+    const existingSections = this.extractManagedSections(existingContent);
+    
+    // Check what needs updating
+    const updates = [];
+    const additions = [];
+    
+    for (const [sectionName, sectionData] of Object.entries(MANAGED_SECTIONS)) {
+      if (existingSections[sectionName]) {
+        // Section exists - check if needs update
+        if (this.needsUpdate(sectionName, existingSections[sectionName].version, existingSections[sectionName].checksum)) {
+          updates.push(sectionName);
+        }
+      } else {
+        // Section doesn't exist - needs to be added
+        additions.push(sectionName);
+      }
+    }
+
+    // If no updates needed, return
+    if (updates.length === 0 && additions.length === 0) {
+      return { updated: false, reason: 'All sections are up to date' };
+    }
+
+    // Create backup if requested
+    if (backupExisting) {
+      const backupPath = `${this.houseRulesPath}.backup.${Date.now()}`;
+      fs.copyFileSync(this.houseRulesPath, backupPath);
+    }
+
+    // Build new content
+    let newContent = existingContent;
+
+    // Update existing sections
+    for (const sectionName of updates) {
+      const existingSection = existingSections[sectionName];
+      const newSection = this.formatSection(sectionName);
+      
+      // Replace the old section with the new one
+      const beforeSection = newContent.substring(0, existingSection.startIndex);
+      const afterSection = newContent.substring(existingSection.endIndex);
+      newContent = beforeSection + newSection + afterSection;
+      
+      // Recalculate positions for remaining sections
+      const diff = newSection.length - (existingSection.endIndex - existingSection.startIndex);
+      for (const section of Object.values(existingSections)) {
+        if (section.startIndex > existingSection.startIndex) {
+          section.startIndex += diff;
+          section.endIndex += diff;
+        }
+      }
+    }
+
+    // Add new sections
+    if (additions.length > 0) {
+      // Find the best place to insert new sections
+      let insertPosition = 0;
+      
+      // Try to insert after the main header
+      const headerMatch = /^# .+\n/m.exec(newContent);
+      if (headerMatch) {
+        insertPosition = headerMatch.index + headerMatch[0].length;
+        
+        // Skip any immediate description
+        const descMatch = /\*\*IMPORTANT:.+\*\*\n/m.exec(newContent.substring(insertPosition));
+        if (descMatch && descMatch.index === 0) {
+          insertPosition += descMatch[0].length;
+        }
+      }
+
+      // Add each new section
+      const sectionsToAdd = additions.map(name => '\n' + this.formatSection(name) + '\n').join('');
+      newContent = newContent.substring(0, insertPosition) + sectionsToAdd + newContent.substring(insertPosition);
+    }
+
+    // Write updated content
+    fs.writeFileSync(this.houseRulesPath, newContent);
+
+    return {
+      updated: true,
+      path: this.houseRulesPath,
+      updatedSections: updates,
+      addedSections: additions,
+      totalChanges: updates.length + additions.length
+    };
+  }
+
+  /**
+   * Get status of house rules
+   */
+  getStatus() {
+    if (!this.houseRulesPath) {
+      return {
+        exists: false,
+        path: null,
+        managedSections: {},
+        needsUpdate: true
+      };
+    }
+
+    const content = fs.readFileSync(this.houseRulesPath, 'utf8');
+    const existingSections = this.extractManagedSections(content);
+    const status = {
+      exists: true,
+      path: this.houseRulesPath,
+      managedSections: {},
+      needsUpdate: false
+    };
+
+    // Check each managed section
+    for (const [sectionName, sectionData] of Object.entries(MANAGED_SECTIONS)) {
+      if (existingSections[sectionName]) {
+        const existing = existingSections[sectionName];
+        const needsUpdate = this.needsUpdate(sectionName, existing.version, existing.checksum);
+        
+        status.managedSections[sectionName] = {
+          installed: true,
+          installedVersion: existing.version,
+          currentVersion: sectionData.version,
+          needsUpdate
+        };
+        
+        if (needsUpdate) {
+          status.needsUpdate = true;
+        }
+      } else {
+        status.managedSections[sectionName] = {
+          installed: false,
+          currentVersion: sectionData.version,
+          needsUpdate: true
+        };
+        status.needsUpdate = true;
+      }
+    }
+
+    return status;
+  }
+}
+
+export default HouseRulesManager;
+
+// CLI interface when run directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const manager = new HouseRulesManager();
+  const command = process.argv[2];
+
+  switch (command) {
+    case 'status':
+      console.log('House Rules Status:', JSON.stringify(manager.getStatus(), null, 2));
+      break;
+      
+    case 'update':
+      manager.updateHouseRules().then(result => {
+        console.log('Update Result:', JSON.stringify(result, null, 2));
+      });
+      break;
+      
+    default:
+      console.log('Usage: node house-rules-manager.js [status|update]');
+  }
+}

package/src/session-coordinator.js

@@ -461,7 +461,13 @@ class SessionCoordinator {
     });
     
     console.log(`\n${CONFIG.colors.yellow}═══ Auto-merge Configuration ═══${CONFIG.colors.reset}`);
-    console.log(`${CONFIG.colors.dim}(Automatically merge today's work into a target branch)${CONFIG.colors.reset}`);
+    console.log(`${CONFIG.colors.dim}Automatically merge your daily work branches into a target branch.${CONFIG.colors.reset}`);
+    console.log();
+    console.log(`${CONFIG.colors.bright}How it works:${CONFIG.colors.reset}`);
+    console.log(`  • The agent creates dated branches (e.g., ${CONFIG.colors.blue}agent_dev_2025-10-01${CONFIG.colors.reset})`);
+    console.log(`  • At the end of each day, your work is automatically merged`);
+    console.log(`  • This keeps your target branch (main/develop) up to date`);
+    console.log(`  • Prevents accumulation of stale feature branches`);
     
     // Ask if they want auto-merge
     const autoMerge = await new Promise((resolve) => {
@@ -784,6 +790,28 @@ INSTRUCTIONS:
 - **Worktree Path:** \`${worktreePath}\`
 - **Branch:** \`${branchName}\`
 
+## 🚨 CRITICAL: File Coordination Protocol
+
+**BEFORE editing any files, you MUST:**
+
+1. **Declare your intent** by creating:
+   \`\`\`json
+   // File: .file-coordination/active-edits/<agent>-${sessionId}.json
+   {
+     "agent": "<your-name>",
+     "session": "${sessionId}",
+     "files": ["list", "files", "to", "edit"],
+     "operation": "edit",
+     "reason": "${task}",
+     "declaredAt": "<ISO-8601-timestamp>",
+     "estimatedDuration": 300
+   }
+   \`\`\`
+
+2. **Check for conflicts** - read all files in \`.file-coordination/active-edits/\`
+3. **Only proceed if no conflicts** - wait or choose different files if blocked
+4. **Release files when done** - delete your declaration after edits
+
 ## Instructions for Claude/Cline
 
 ### Step 1: Navigate to Your Worktree
@@ -797,18 +825,25 @@ git branch --show-current
 # Should output: ${branchName}
 \`\`\`
 
-### Step 3: Work on Your Task
+### Step 3: Declare Files Before Editing
+Create your declaration in \`.file-coordination/active-edits/\`
+
+### Step 4: Work on Your Task
 Make changes for: **${task}**
 
-### Step 4: Commit Your Changes
+### Step 5: Commit Your Changes
 Write your commit message to the session-specific file:
 \`\`\`bash
 echo "feat: your commit message here" > .devops-commit-${sessionId}.msg
 \`\`\`
 
-### Step 5: Automatic Processing
+### Step 6: Release Your File Locks
+Delete your declaration from \`.file-coordination/active-edits/\`
+
+### Step 7: Automatic Processing
 The DevOps agent will automatically:
 - Detect your changes
+- Check for coordination conflicts
 - Read your commit message
 - Commit and push to the remote repository
 - Clear the message file
@@ -853,11 +888,21 @@ The DevOps agent will automatically:
     console.log(`- Working Directory: ${instructions.worktreePath}`);
     console.log(`- Task: ${task || 'development'}`);
     console.log(``);
-    console.log(`Please switch to this directory before making any changes:`);
-    console.log(`cd "${instructions.worktreePath}"`);
+    console.log(`CRITICAL FIRST STEP:`);
+    console.log(`1. Read and follow the house rules: cat "${instructions.worktreePath}/houserules.md"`);
+    console.log(`2. Switch to the working directory: cd "${instructions.worktreePath}"`);
+    console.log(``);
+    console.log(`FILE COORDINATION PROTOCOL (from house rules at ${instructions.worktreePath}/houserules.md):`);
+    console.log(`Before editing ANY files, you MUST:`);
+    console.log(`- Declare your intent in .file-coordination/active-edits/<agent>-${sessionId}.json`);
+    console.log(`- Check for conflicts with other agents`);
+    console.log(`- Only edit files you've declared`);
+    console.log(`- Release files when done`);
     console.log(``);
     console.log(`Write commit messages to: .devops-commit-${sessionId}.msg`);
     console.log(`The DevOps agent will automatically commit and push changes.`);
+    console.log(``);
+    console.log(`Remember: ALWAYS check house rules first for the latest protocols!`);
     console.log();
     
     console.log(`${CONFIG.colors.yellow}══════════════════════════════════════════════════════════════${CONFIG.colors.reset}`);

package/src/setup-cs-devops-agent.js

@@ -735,7 +735,8 @@ export AC_MSG_MIN_BYTES="20"
 export AC_DEBOUNCE_MS="1500"
 export AC_MSG_DEBOUNCE_MS="3000"
 export AC_CLEAR_MSG_WHEN="push"
-export AC_ROLLOVER_PROMPT="true"
+# Daily rollover is automatic - no prompting needed
+export AC_ROLLOVER_PROMPT="false"
 export AC_DEBUG="false"
 
 # Check for debug flag
@@ -784,7 +785,8 @@ AC_MSG_DEBOUNCE_MS=3000
 
 # Behavior
 AC_CLEAR_MSG_WHEN=push
-AC_ROLLOVER_PROMPT=true
+# Daily rollover is automatic
+AC_ROLLOVER_PROMPT=false
 AC_DEBUG=false
 `;
   
@@ -826,7 +828,7 @@ function printInstructions(initials) {
   log.title('🎯 Daily Workflow:');
   console.log('');
   console.log(`• Your daily branches will be: ${colors.bright}dev_${initials}_YYYY-MM-DD${colors.reset}`);
-  console.log('• The worker handles day rollover automatically');
+  console.log('• The worker automatically creates new daily branches at midnight');
   console.log('• Commits require valid conventional format (feat/fix/docs/etc)');
   console.log('• Message file is cleared after successful push');
   console.log('');