fraim-framework 2.0.34 → 2.0.36

package/registry/rules/software-development-lifecycle.md

@@ -1,105 +1,105 @@
-# Software Development Lifecycle
-
-## INTENT
-To provide a structured, phase-based approach to issue resolution that ensures proper planning, implementation, testing, and cleanup while maintaining coordination with other agents and respecting project governance.
-
-## PRINCIPLES
-- **Phase-Based Development**: Clear phases with specific deliverables
-- **Branch Safety**: Never work on master, always use feature branches
-- **Local Development**: Work in isolated clones to prevent conflicts
-- **Coordination**: Use GitHub for agent coordination and status management
-- **Governance**: Respect CODEOWNERS and project policies
-
-## CORE WORKFLOW
-Always work on the feature branch for the current issue: `feature/<issue#>-<kebab-title>`. Never push to master.
-
-### Development Workflow
-1. **Clone Setup**: Work in your own cloned repository folder. Folder name should be `Ashley Calendar AI - Issue {issue_number}`
-2. **Branch Management**: Create/checkout feature branch for your issue
-3. **Local Development**: Make changes, run tests locally
-4. **Check before commit**: Only commit after approval from the user.
-5. **Remote Coordination**: Use GitHub MCP for issue labels
-
-## MANDATORY PRE-COMMIT VALIDATION
-Before ANY commit, run: `git branch` and verify NOT on master
-
-## PHASES
-
-### Design Phase
-- **Trigger**: Set ISSUE to `phase:design`
-- **Deliverable**: Create RFC document
-- **Status**: Automatically set to `status:wip`
-
-### Implementation Phase
-- **Trigger**: Set ISSUE to `phase:impl`
-- **Deliverable**: Working code with tests
-- **Status**: Set to `status:needs-review` when ready
-
-## STATUS MANAGEMENT
-- **WIP**: Automatically set when entering new phase
-- **Needs Review**: Set this when work is ready for review
-- **Complete**: Automatically set when PR is approved
-
-## EXAMPLES
-
-### Good: Proper Phase Management
-```
-Issue #84: "Fix calendar sync timeout"
-1. Set phase:design → Create RFC for retry logic
-2. Set phase:impl → Implement exponential backoff
-3. Set status:needs-review → Ready for code review
-4. PR approved → Set status:complete
-Result: Clear progression through phases
-```
-
-### Bad: Skipping Phases
-```
-Issue #84: "Fix calendar sync timeout"
-1. Jump straight to coding without design
-2. No RFC created
-3. Implementation lacks proper planning
-Result: Incomplete solution, potential rework
-```
-
-## PRE-PHASE VALIDATION
-
-### Before Starting Any Phase
-Agents MUST complete validation checklist:
-
-1. **Read Relevant Rules**:
-   - [ ] Read `get_fraim_file({ path: "rules/software-development-lifecycle.md" })`
-   - [ ] Read phase-specific workflow via `get_fraim_file` (e.g. `workflows/product-building/design.md`)
-   - [ ] Read retrospectives folder thoroughly and understand past learnings
-
-2. **Verify Environment**:
-   - [ ] Confirm working directory is correct
-   - [ ] Verify branch exists and is checked out
-   - [ ] Check issue labels are correct
-
-3. **Template Validation**:
-   - [ ] Locate correct template file
-   - [ ] Verify template exists and is readable
-   - [ ] Confirm naming convention understanding
-
-4. **Technical Understanding**:
-   - [ ] Understand relevant technical patterns for the issue
-   - [ ] Plan test strategy for core functionality
-
-### Validation Failure Response
-If any validation step fails:
-1. Stop work immediately
-2. Read missing documentation
-3. Ask clarifying questions if needed
-4. Resume only after validation complete
-
-## CLEANUP
-When user confirms code is correctly merged into master, confirm with the user, then 
-- delete remote branch
-- delete local branch
-- remove your local clone folder:
-```
-cd ..
-Remove-Item -Recurse -Force "Ashley Calendar AI - Issue {issue_number}"
-```
-
+# Software Development Lifecycle
+
+## INTENT
+To provide a structured, phase-based approach to issue resolution that ensures proper planning, implementation, testing, and cleanup while maintaining coordination with other agents and respecting project governance.
+
+## PRINCIPLES
+- **Phase-Based Development**: Clear phases with specific deliverables
+- **Branch Safety**: Never work on master, always use feature branches
+- **Local Development**: Work in isolated clones to prevent conflicts
+- **Coordination**: Use GitHub for agent coordination and status management
+- **Governance**: Respect CODEOWNERS and project policies
+
+## CORE WORKFLOW
+Always work on the feature branch for the current issue: `feature/<issue#>-<kebab-title>`. Never push to master.
+
+### Development Workflow
+1. **Clone Setup**: Work in your own cloned repository folder. Folder name should be `Ashley Calendar AI - Issue {issue_number}`
+2. **Branch Management**: Create/checkout feature branch for your issue
+3. **Local Development**: Make changes, run tests locally
+4. **Check before commit**: Only commit after approval from the user.
+5. **Remote Coordination**: Use GitHub MCP for issue labels
+
+## MANDATORY PRE-COMMIT VALIDATION
+Before ANY commit, run: `git branch` and verify NOT on master
+
+## PHASES
+
+### Design Phase
+- **Trigger**: Set ISSUE to `phase:design`
+- **Deliverable**: Create RFC document
+- **Status**: Automatically set to `status:wip`
+
+### Implementation Phase
+- **Trigger**: Set ISSUE to `phase:impl`
+- **Deliverable**: Working code with tests
+- **Status**: Set to `status:needs-review` when ready
+
+## STATUS MANAGEMENT
+- **WIP**: Automatically set when entering new phase
+- **Needs Review**: Set this when work is ready for review
+- **Complete**: Automatically set when PR is approved
+
+## EXAMPLES
+
+### Good: Proper Phase Management
+```
+Issue #84: "Fix calendar sync timeout"
+1. Set phase:design → Create RFC for retry logic
+2. Set phase:impl → Implement exponential backoff
+3. Set status:needs-review → Ready for code review
+4. PR approved → Set status:complete
+Result: Clear progression through phases
+```
+
+### Bad: Skipping Phases
+```
+Issue #84: "Fix calendar sync timeout"
+1. Jump straight to coding without design
+2. No RFC created
+3. Implementation lacks proper planning
+Result: Incomplete solution, potential rework
+```
+
+## PRE-PHASE VALIDATION
+
+### Before Starting Any Phase
+Agents MUST complete validation checklist:
+
+1. **Read Relevant Rules**:
+   - [ ] Read `get_fraim_file({ path: "rules/software-development-lifecycle.md" })`
+   - [ ] Read phase-specific workflow via `get_fraim_file` (e.g. `workflows/product-building/design.md`)
+   - [ ] Read retrospectives folder thoroughly and understand past learnings
+
+2. **Verify Environment**:
+   - [ ] Confirm working directory is correct
+   - [ ] Verify branch exists and is checked out
+   - [ ] Check issue labels are correct
+
+3. **Template Validation**:
+   - [ ] Locate correct template file
+   - [ ] Verify template exists and is readable
+   - [ ] Confirm naming convention understanding
+
+4. **Technical Understanding**:
+   - [ ] Understand relevant technical patterns for the issue
+   - [ ] Plan test strategy for core functionality
+
+### Validation Failure Response
+If any validation step fails:
+1. Stop work immediately
+2. Read missing documentation
+3. Ask clarifying questions if needed
+4. Resume only after validation complete
+
+## CLEANUP
+When user confirms code is correctly merged into master, confirm with the user, then 
+- delete remote branch
+- delete local branch
+- remove your local clone folder:
+```
+cd ..
+Remove-Item -Recurse -Force "Ashley Calendar AI - Issue {issue_number}"
+```
+
 Respect CODEOWNERS; don't modify auth/CI without approval.

package/registry/scripts/cleanup-branch.ts

@@ -0,0 +1,341 @@
+#!/usr/bin/env npx tsx
+
+import { execSync } from 'child_process';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import dotenv from 'dotenv';
+
+// Load environment variables
+dotenv.config({ override: true });
+
+// Self-contained utility functions (no FRAIM internal imports)
+function extractIssueNumber(branchName: string): string {
+  const match = branchName.match(/(\d+)/);
+  return match ? match[1] : '';
+}
+
+function getCurrentGitBranch(): string {
+  try {
+    return execSync('git branch --show-current', { encoding: 'utf8' }).trim();
+  } catch (error) {
+    return 'unknown';
+  }
+}
+
+interface FraimConfig {
+  persona: { name: string; displayNamePattern: string; emailSignature: string };
+  git: { repoOwner: string; repoName: string };
+  database: { identityCollection: string; executiveCollection: string };
+  marketing: { websiteUrl?: string; chatUrl?: string };
+}
+
+function loadClientConfig(): FraimConfig {
+  const configPath = join(process.cwd(), '.fraim', 'config.json');
+  if (!existsSync(configPath)) {
+    throw new Error('.fraim/config.json not found. Run fraim init first.');
+  }
+  return JSON.parse(readFileSync(configPath, 'utf-8'));
+}
+
+function getEnvOr(keys: string[], fallback: string): string {
+  for (const key of keys) {
+    const value = process.env[key];
+    if (value && value.length) return value;
+  }
+  return fallback;
+}
+
+interface CleanupOptions {
+  branchName?: string;
+  force?: boolean;
+  skipProjectCleanup?: boolean;
+  skipGit?: boolean;
+}
+
+class BranchCleanup {
+  private options: CleanupOptions;
+
+  constructor(options: CleanupOptions = {}) {
+    this.options = {
+      branchName: options.branchName,
+      force: options.force || false,
+      skipProjectCleanup: options.skipProjectCleanup || false,
+      skipGit: options.skipGit || false,
+    };
+  }
+
+  private async insertYourCodeHere(branchName: string): Promise<void> {
+    const branchPattern = "branch_" + extractIssueNumber(branchName) + "%";
+    this.log(`Attempting to fetch and run DB cleanup for pattern: ${branchPattern}`);
+
+    // Historically this called: npx tsx scripts/database/cleanup-mongo-schemas.ts
+    // In FRAIM 2.0, we should fetch it if possible, or skip if it's an internal-only script
+    // that doesn't exist in the registry but was incorrectly referenced.
+
+    // NOTE: In this specific case, cleanup-mongo-schemas.ts is likely an internal script.
+    // If it's not in the registry, get_fraim_file will fail.
+    // For now, we fix the path to be more agnostic or explicitly documented as a dependency.
+
+    try {
+      // NOTE: Users should define their own cleanup script location in .fraim/config.json
+      // or the agent should fetch it. For now, we try to run it from a standard location
+      // if it exists, but we don't hardcode it as a requirement for the script to run.
+      const cleanupScript = process.env.FRAIM_PROJECT_CLEANUP_SCRIPT || (['scripts', 'database', 'cleanup-mongo-schemas.ts'].join('/'));
+      this.log(`Checking for project cleanup script: ${cleanupScript}`);
+
+      await this.executeCommand(
+        `npx tsx ${cleanupScript} "${branchPattern}"`,
+        'Run project-specific cleanup script'
+      );
+    } catch (e) {
+      this.log('Skipping project-specific cleanup (script not found or failed).', 'info');
+    }
+  }
+
+
+  private log(message: string, level: 'info' | 'warn' | 'error' | 'success' = 'info') {
+    const timestamp = new Date().toISOString();
+    const prefix = {
+      info: 'ℹ️ ',
+      warn: '⚠️ ',
+      error: '❌',
+      success: '✅'
+    }[level];
+
+    console.log(`${prefix} [${timestamp}] ${message}`);
+  }
+
+  private async executeCommand(command: string, description: string): Promise<string> {
+    this.log(`Executing: ${description}`);
+
+    try {
+      const result = execSync(command, {
+        encoding: 'utf8',
+        stdio: 'pipe',
+        cwd: process.cwd()
+      });
+      this.log(`Success: ${description}`, 'success');
+      return result;
+    } catch (error: any) {
+      this.log(`Failed: ${description} - ${error.message}`, 'error');
+      throw error;
+    }
+  }
+
+  private async getCurrentBranch(): Promise<string> {
+    try {
+      const result = await this.executeCommand('git branch --show-current', 'Get current branch');
+      return result.trim();
+    } catch (error) {
+      this.log('Could not determine current branch', 'warn');
+      return 'unknown';
+    }
+  }
+
+  private async getBranchName(): Promise<string> {
+    if (this.options.branchName) {
+      return this.options.branchName;
+    }
+
+    const currentBranch = await this.getCurrentBranch();
+    if (currentBranch === 'master' || currentBranch === 'main') {
+      throw new Error('Cannot cleanup master/main branch. Please specify a feature branch name.');
+    }
+
+    return currentBranch;
+  }
+
+  private async checkBranchExists(branchName: string, remote: boolean = false): Promise<boolean> {
+    try {
+      const command = remote
+        ? `git ls-remote --heads origin ${branchName}`
+        : `git branch --list ${branchName}`;
+
+      const result = await this.executeCommand(command, `Check if ${remote ? 'remote' : 'local'} branch exists`);
+      return result.trim().length > 0;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  private async doProjectSpecificCleanup(branchName: string): Promise<void> {
+    try {
+      if (this.options.skipProjectCleanup) {
+        this.log('Skipping project-specific cleanup', 'warn');
+        return;
+      }
+
+      this.log('Starting project-specific cleanup...');
+
+      await this.insertYourCodeHere(branchName);
+
+      this.log('Project-specific cleanup completed successfully', 'success');
+    } catch (error: any) {
+      this.log(`Project-specific cleanup failed: ${error.message}`, 'error');
+      if (!this.options.force) {
+        throw error;
+      }
+    }
+  }
+
+  private async cleanupGitBranches(branchName: string): Promise<void> {
+    if (this.options.skipGit) {
+      this.log('Skipping Git cleanup', 'warn');
+      return;
+    }
+
+    this.log(`Starting Git branch cleanup for: ${branchName}`);
+
+    // Check if we're on the branch we want to delete
+    const currentBranch = await this.getCurrentBranch();
+    if (currentBranch === branchName) {
+      this.log(`Currently on branch ${branchName}, switching to master first`, 'warn');
+      await this.executeCommand('git checkout master', 'Switch to master branch');
+    }
+
+    // Delete remote branch
+    const remoteExists = await this.checkBranchExists(branchName, true);
+    if (remoteExists) {
+      this.log(`Deleting remote branch: origin/${branchName}`);
+      await this.executeCommand(`git push origin --delete ${branchName}`, `Delete remote branch ${branchName}`);
+    } else {
+      this.log(`Remote branch origin/${branchName} does not exist`, 'info');
+    }
+
+    // Delete local branch
+    const localExists = await this.checkBranchExists(branchName, false);
+    if (localExists) {
+      this.log(`Deleting local branch: ${branchName}`);
+      await this.executeCommand(`git branch -D ${branchName}`, `Delete local branch ${branchName}`);
+    } else {
+      this.log(`Local branch ${branchName} does not exist`, 'info');
+    }
+
+    // Clean up any untracked files
+    this.log('Cleaning up untracked files...');
+    await this.executeCommand('git clean -fd', 'Remove untracked files and directories');
+
+    // Reset any uncommitted changes
+    this.log('Resetting uncommitted changes...');
+    await this.executeCommand('git reset --hard HEAD', 'Reset to HEAD');
+
+    this.log('Git branch cleanup completed', 'success');
+  }
+
+
+  private async verifyCleanup(branchName: string): Promise<void> {
+    this.log('Verifying cleanup...');
+
+    // Verify branch deletion
+    const remoteExists = await this.checkBranchExists(branchName, true);
+    const localExists = await this.checkBranchExists(branchName, false);
+
+    if (remoteExists || localExists) {
+      this.log(`Warning: Branch ${branchName} still exists (remote: ${remoteExists}, local: ${localExists})`, 'warn');
+    } else {
+      this.log(`Branch ${branchName} successfully deleted`, 'success');
+    }
+
+    // Verify we're on master
+    const currentBranch = await this.getCurrentBranch();
+    if (currentBranch === 'master' || currentBranch === 'main') {
+      this.log('Currently on master/main branch', 'success');
+    } else {
+      this.log(`Warning: Not on master branch, currently on ${currentBranch}`, 'warn');
+    }
+
+    this.log('Cleanup verification completed', 'success');
+  }
+
+  async cleanup(): Promise<void> {
+    try {
+      this.log('🚀 Starting branch cleanup process...');
+
+      const branchName = await this.getBranchName();
+      this.log(`Target branch: ${branchName}`);
+
+      // Step 1: Project-specific cleanup
+      await this.doProjectSpecificCleanup(branchName);
+
+      // Step 2: Git branch cleanup
+      await this.cleanupGitBranches(branchName);
+
+      // Step 3: Verification
+      await this.verifyCleanup(branchName);
+
+      this.log('🎉 Branch cleanup completed successfully!', 'success');
+
+    } catch (error: any) {
+      this.log(`Cleanup failed: ${error.message}`, 'error');
+      if (!this.options.force) {
+        process.exit(1);
+      }
+    }
+  }
+}
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const options: CleanupOptions = {};
+
+// Parse arguments
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+
+  switch (arg) {
+    case '--branch':
+    case '-b':
+      options.branchName = args[++i];
+      break;
+    case '--force':
+    case '-f':
+      options.force = true;
+      break;
+    case '--skip-project-cleanup':
+      options.skipProjectCleanup = true;
+      break;
+    case '--skip-git':
+      options.skipGit = true;
+      break;
+    case '--help':
+    case '-h':
+      console.log(`
+🧹 Branch Cleanup Script
+
+Usage:
+  npx tsx scripts/cleanup-branch.ts [options]
+
+Options:
+  --branch, -b <name>              Specific branch name to cleanup (default: current branch)
+  --force, -f                      Continue even if some operations fail
+  --skip-project-cleanup           Skip project-specific cleanup
+  --skip-git                       Skip Git branch deletion
+  --help, -h                       Show this help message
+
+Examples:
+  # Cleanup current branch with default settings
+  npx tsx <cleanup-script-path>
+
+  # Cleanup specific branch
+  npx tsx <cleanup-script-path> --branch feature/123
+
+  # Force cleanup even if some operations fail
+  npx tsx <cleanup-script-path> --force
+
+  # Skip project-specific cleanup (only do Git cleanup)
+  npx tsx <cleanup-script-path> --skip-project-cleanup
+
+This script performs the following cleanup operations:
+1. 🗄️  Project-specific cleanup (calls configured cleanup script)
+2. 🌿 Git branch deletion (remote and local)
+3. ✅ Verification of cleanup completion
+
+⚠️  WARNING: This script will permanently delete branches and data!
+      `);
+      process.exit(0);
+  }
+}
+
+// Run the cleanup
+const cleanup = new BranchCleanup(options);
+cleanup.cleanup();