fraim-framework 2.0.27 → 2.0.33

package/registry/rules/hitl-ppe-record-analysis.md

@@ -1,302 +1,302 @@
-# HITL PPE Record Analysis & Debugging Patterns
-
-## INTENT
-To provide agents with systematic patterns for analyzing HITL (Human-In-The-Loop) records from PPE database, categorizing issues, and implementing appropriate fixes. This rule ensures consistent analysis and prevents overfitting or missing root causes.
-
-## PRINCIPLES
-- **Systematic Analysis**: Always follow a structured approach (query → analyze → categorize → fix)
-- **Categorize Before Fixing**: Distinguish systemic issues from executive preferences before implementing
-- **Leverage Existing Infrastructure**: Check if existing features can handle needs before adding new fields
-- **Minimal Fixes**: Focus on smallest changes that solve the problem
-- **Avoid Overfitting**: Use generic examples, never specific person names or scenarios
-
-## CORE WORKFLOW PATTERN
-
-### The "Query → Filter → Analyze → Categorize → Fix → Document" Pattern
-
-```
-1. QUERY: Connect to PPE database and query HITL records
-2. FILTER: Exclude test/synthetic data (e.g., ChatGPT records)
-3. ANALYZE: Extract reviewer feedback patterns and identify issues
-4. CATEGORIZE: Divide into systemic (BAML/code) vs preferences (configurable)
-5. FIX: Implement minimal fixes for systemic issues
-6. DOCUMENT: Create GitHub issues for preference gaps
-```
-
-## RULE 1: Data Collection & Filtering
-
-### When Querying HITL Records
-
-**Always filter by source:**
-- Exclude test/synthetic records: `Inputs.source != 'chatgpt'`
-- Handle missing source fields: Use `$or` with `$exists: false`
-- Filter for non-empty reviewer feedback: `ReviewerFeeback: { $exists: true, $regex: /\S/ }`
-
-**Query Pattern:**
-```typescript
-const query = {
-  ReviewerFeeback: {
-    $exists: true,
-    $regex: /\S/  // At least one non-whitespace character
-  },
-  $or: [
-    { 'Inputs.source': { $exists: false } },
-    { 'Inputs.source': { $ne: 'chatgpt' } }
-  ]
-};
-```
-
-**Verification:**
-- [ ] Verify record count makes sense (not too many/too few)
-- [ ] Check that filtered results exclude test data
-- [ ] Confirm reviewer feedback exists and is non-empty
-
-## RULE 2: Issue Categorization
-
-### Before Implementing Fixes, Categorize All Issues
-
-**Systemic Issues (BAML/Code Fixes):**
-- ✅ Affect all executives universally
-- ✅ Examples: Fake conference links, date logic errors, missing calendar data extraction, accountability violations
-- **Action**: Fix in BAML prompts or code logic
-
-**Executive Preferences (Configurable):**
-- ✅ Differ per executive
-- ✅ Examples: Time preferences (avoid 6-7pm), location defaults (virtual vs in-person), verbosity level
-- **Action**: Add to ExecutivePreferences schema OR use existing infrastructure (focus blocks)
-
-**Hybrid Issues:**
-- ✅ Core logic is systemic, but thresholds/preferences differ
-- **Action**: Implement systemic fix with configurable parameters
-
-**Categorization Checklist:**
-- [ ] Identify which category each issue belongs to
-- [ ] Verify categorization makes sense (would this affect all executives?)
-- [ ] Check if existing infrastructure can handle preference needs
-- [ ] Only add new fields after confirming no existing solution
-
-## RULE 3: Leverage Existing Infrastructure
-
-### Before Adding New Preference Fields
-
-**Check if focus blocks can handle it:**
-- Time-based preferences (avoided windows, thresholds) → Use HIGH protection focus blocks
-- Example: "Avoid 6-7pm meetings" → Create focus block with HIGH protection for 6-7pm
-
-**Check if rules can handle it:**
-- Natural language rules may cover edge cases
-- Example: "Prefer in-person for direct reports" → Could use rule with condition
-
-**Only add new fields if:**
-- ❌ No existing infrastructure can handle the use case
-- ✅ The preference is structural (location type, duration defaults)
-- ✅ It needs explicit configuration (not inferable from behavior)
-
-**Infrastructure Check:**
-- [ ] Check `ExecutivePreferences` schema for existing fields
-- [ ] Check if `focus_blocks` can handle time-based preferences
-- [ ] Check if `rules` can handle natural language preferences
-- [ ] Only add new fields after confirming no existing solution
-
-## RULE 4: BAML Prompt Updates
-
-### When Fixing Systemic Issues in BAML
-
-**Add explicit instructions:**
-- Don't rely on implicit understanding
-- Use phrases like "NEVER", "CRITICAL", "MUST NOT"
-- Example: "NEVER generate conference links" not "Don't generate conference links"
-
-**Use multiple locations:**
-- Add rules in all relevant sections
-- Example: Conference link prohibition → LocationGuidelines, EmailResponseGuidelines, CalendarInviteDetails
-
-**Provide examples:**
-- Include both correct ✅ and incorrect ❌ examples
-- Show what NOT to do, not just what to do
-
-**List banned phrases explicitly:**
-- When fixing verbosity/accountability, list specific phrases to avoid
-- Example: "DO NOT say: 'I'll note it for the team', 'I can take responsibility', etc."
-
-**Avoid overfitting:**
-- ❌ Never use specific person names ("Lindy", "Sarah")
-- ✅ Use generic examples ("a person", "someone coordinating")
-- ✅ Use placeholder variables when possible
-
-**BAML Update Checklist:**
-- [ ] No specific person names (generic examples only)
-- [ ] Explicit instructions (NEVER, CRITICAL, MUST NOT)
-- [ ] Multiple relevant sections updated if needed
-- [ ] Banned phrases listed explicitly
-- [ ] Examples provided (correct and incorrect)
-- [ ] Regenerated BAML client (`npm run generate`)
-
-## RULE 5: Iterative Refinement
-
-### For Complex Rule Updates
-
-**Start with core rule:**
-- Add basic rule first
-- Test to see if it works
-
-**Test edge cases:**
-- Identify problematic phrases/behaviors
-- Look for variations of the issue
-
-**Iterate:**
-- Add specific exceptions and banned phrases
-- Refine based on user feedback
-
-**Regenerate and verify:**
-- Always run `npm run generate` after changes
-- Check for lint errors (note pre-existing vs new)
-
-**Refinement Checklist:**
-- [ ] Core rule added
-- [ ] Edge cases identified
-- [ ] Specific exceptions added
-- [ ] BAML client regenerated
-- [ ] Lint errors checked
-
-## RULE 6: Minimal Fixes Strategy
-
-### When Implementing Fixes
-
-**Focus on root cause:**
-- Don't fix symptoms, fix the underlying issue
-- Example: Don't add workarounds, fix the prompt logic
-
-**Smallest change:**
-- Make the minimal change that solves the problem
-- Avoid over-engineering
-
-**Multiple locations if needed:**
-- If issue appears in multiple places, fix all instances
-- Don't partially fix
-
-**Don't over-engineer:**
-- Avoid adding complex logic when simple rule updates work
-- Example: Adding validation code when prompt instruction works
-
-**Minimal Fix Checklist:**
-- [ ] Root cause identified (not just symptom)
-- [ ] Smallest possible change made
-- [ ] All instances fixed if issue appears multiple times
-- [ ] No unnecessary complexity added
-
-## RULE 7: Documentation
-
-### After Analysis
-
-**Create analysis document:**
-- Document findings, patterns, and recommendations
-- Include specific examples from records
-- Link to source data
-
-**Create GitHub issues:**
-- For gaps that can't be fixed immediately (preferences)
-- Include clear recommendations and implementation points
-- Label appropriately (enhancement, area:preferences, etc.)
-
-**Link to analysis:**
-- Reference source documents in issues and code comments
-- Include record IDs for traceability
-
-**Record patterns:**
-- Document patterns for future reference
-- Note what worked and what didn't
-
-**Documentation Checklist:**
-- [ ] Analysis document created with findings
-- [ ] GitHub issues created for preference gaps
-- [ ] Source documents linked
-- [ ] Patterns documented for future reference
-
-## RULE 8: Testing & Validation
-
-### Before Considering Fixes Complete
-
-**Regenerate BAML client:**
-- Always run `npm run generate` after BAML changes
-- Verify generation succeeds
-
-**Check lint errors:**
-- Verify no new errors introduced
-- Note any pre-existing errors (don't fix unrelated issues)
-
-**Verify changes:**
-- Confirm changes are in correct locations
-- Check that all relevant sections updated
-
-**Don't commit prematurely:**
-- User may request multiple iterations
-- Wait for explicit commit instruction
-
-**Testing Checklist:**
-- [ ] BAML client regenerated (`npm run generate`)
-- [ ] Lint errors checked (no new errors)
-- [ ] Changes verified in correct locations
-- [ ] Not committed (wait for user instruction)
-
-## COMMON PATTERNS
-
-### Pattern 1: Time Window Preferences
-**Issue**: "Executive prefers not to have 6-7pm meetings"  
-**Solution**: Use focus blocks with HIGH protection (don't add new field)  
-**Implementation**: Create focus block for 6-7pm with `protection_level: HIGH`
-
-### Pattern 2: Location Defaults
-**Issue**: "Location incorrectly defaulted to virtual when should be in-person"  
-**Solution**: Add `default_meeting_location_type` to ExecutivePreferences  
-**Implementation**: New field in schema, use in BAML when location not specified
-
-### Pattern 3: Accountability Violations
-**Issue**: "Ashley took over coordination when someone else was coordinating"  
-**Solution**: Add explicit rules to respect existing accountability  
-**Implementation**: Update AccountabilityRules template, add banned phrases list
-
-### Pattern 4: Date Interpretation Errors
-**Issue**: "This week included past dates"  
-**Solution**: Add validation rules to never include past dates  
-**Implementation**: Update date interpretation rules in calendar_intent.baml
-
-## ANTI-PATTERNS TO AVOID
-
-1. **❌ Adding new fields when focus blocks work**: Use existing infrastructure first
-2. **❌ Using specific names in prompts**: Always use generic examples
-3. **❌ Fixing symptoms not root causes**: Dig deeper to find underlying issue
-4. **❌ Over-engineering solutions**: Simple prompt updates often work better than complex logic
-5. **❌ Skipping categorization**: Always categorize before fixing
-
-## RELATED RULES
-
-- `.ai-agents/rules/successful-debugging-patterns.md` - General debugging patterns
-- `.ai-agents/rules/code-quality-and-debugging-patterns.md` - Code quality standards
-- `.ai-agents/rules/ashley-architecture.md` - BAML architecture guidelines
-
-## EXAMPLES
-
-### Good: Systematic Analysis
-```
-1. Query PPE database with proper filters
-2. Identify 18 records with reviewer feedback
-3. Categorize: 7 systemic, 3 preferences
-4. Fix systemic issues in BAML
-5. Create GitHub issue for preferences
-6. Document in retrospective
-```
-
-### Bad: Ad-hoc Fixes
-```
-1. See one issue
-2. Fix it immediately
-3. Don't check for patterns
-4. Don't categorize
-5. Don't document
-```
-
----
-
-**Source**: Derived from retrospective `retrospectives/ppe-hitl-feedback-analysis-debugging-patterns.mdc`  
-**Last Updated**: 2025-11-05
+# HITL PPE Record Analysis & Debugging Patterns
+
+## INTENT
+To provide agents with systematic patterns for analyzing HITL (Human-In-The-Loop) records from PPE database, categorizing issues, and implementing appropriate fixes. This rule ensures consistent analysis and prevents overfitting or missing root causes.
+
+## PRINCIPLES
+- **Systematic Analysis**: Always follow a structured approach (query → analyze → categorize → fix)
+- **Categorize Before Fixing**: Distinguish systemic issues from executive preferences before implementing
+- **Leverage Existing Infrastructure**: Check if existing features can handle needs before adding new fields
+- **Minimal Fixes**: Focus on smallest changes that solve the problem
+- **Avoid Overfitting**: Use generic examples, never specific person names or scenarios
+
+## CORE WORKFLOW PATTERN
+
+### The "Query → Filter → Analyze → Categorize → Fix → Document" Pattern
+
+```
+1. QUERY: Connect to PPE database and query HITL records
+2. FILTER: Exclude test/synthetic data (e.g., ChatGPT records)
+3. ANALYZE: Extract reviewer feedback patterns and identify issues
+4. CATEGORIZE: Divide into systemic (BAML/code) vs preferences (configurable)
+5. FIX: Implement minimal fixes for systemic issues
+6. DOCUMENT: Create GitHub issues for preference gaps
+```
+
+## RULE 1: Data Collection & Filtering
+
+### When Querying HITL Records
+
+**Always filter by source:**
+- Exclude test/synthetic records: `Inputs.source != 'chatgpt'`
+- Handle missing source fields: Use `$or` with `$exists: false`
+- Filter for non-empty reviewer feedback: `ReviewerFeeback: { $exists: true, $regex: /\S/ }`
+
+**Query Pattern:**
+```typescript
+const query = {
+  ReviewerFeeback: {
+    $exists: true,
+    $regex: /\S/  // At least one non-whitespace character
+  },
+  $or: [
+    { 'Inputs.source': { $exists: false } },
+    { 'Inputs.source': { $ne: 'chatgpt' } }
+  ]
+};
+```
+
+**Verification:**
+- [ ] Verify record count makes sense (not too many/too few)
+- [ ] Check that filtered results exclude test data
+- [ ] Confirm reviewer feedback exists and is non-empty
+
+## RULE 2: Issue Categorization
+
+### Before Implementing Fixes, Categorize All Issues
+
+**Systemic Issues (BAML/Code Fixes):**
+- ✅ Affect all executives universally
+- ✅ Examples: Fake conference links, date logic errors, missing calendar data extraction, accountability violations
+- **Action**: Fix in BAML prompts or code logic
+
+**Executive Preferences (Configurable):**
+- ✅ Differ per executive
+- ✅ Examples: Time preferences (avoid 6-7pm), location defaults (virtual vs in-person), verbosity level
+- **Action**: Add to ExecutivePreferences schema OR use existing infrastructure (focus blocks)
+
+**Hybrid Issues:**
+- ✅ Core logic is systemic, but thresholds/preferences differ
+- **Action**: Implement systemic fix with configurable parameters
+
+**Categorization Checklist:**
+- [ ] Identify which category each issue belongs to
+- [ ] Verify categorization makes sense (would this affect all executives?)
+- [ ] Check if existing infrastructure can handle preference needs
+- [ ] Only add new fields after confirming no existing solution
+
+## RULE 3: Leverage Existing Infrastructure
+
+### Before Adding New Preference Fields
+
+**Check if focus blocks can handle it:**
+- Time-based preferences (avoided windows, thresholds) → Use HIGH protection focus blocks
+- Example: "Avoid 6-7pm meetings" → Create focus block with HIGH protection for 6-7pm
+
+**Check if rules can handle it:**
+- Natural language rules may cover edge cases
+- Example: "Prefer in-person for direct reports" → Could use rule with condition
+
+**Only add new fields if:**
+- ❌ No existing infrastructure can handle the use case
+- ✅ The preference is structural (location type, duration defaults)
+- ✅ It needs explicit configuration (not inferable from behavior)
+
+**Infrastructure Check:**
+- [ ] Check `ExecutivePreferences` schema for existing fields
+- [ ] Check if `focus_blocks` can handle time-based preferences
+- [ ] Check if `rules` can handle natural language preferences
+- [ ] Only add new fields after confirming no existing solution
+
+## RULE 4: BAML Prompt Updates
+
+### When Fixing Systemic Issues in BAML
+
+**Add explicit instructions:**
+- Don't rely on implicit understanding
+- Use phrases like "NEVER", "CRITICAL", "MUST NOT"
+- Example: "NEVER generate conference links" not "Don't generate conference links"
+
+**Use multiple locations:**
+- Add rules in all relevant sections
+- Example: Conference link prohibition → LocationGuidelines, EmailResponseGuidelines, CalendarInviteDetails
+
+**Provide examples:**
+- Include both correct ✅ and incorrect ❌ examples
+- Show what NOT to do, not just what to do
+
+**List banned phrases explicitly:**
+- When fixing verbosity/accountability, list specific phrases to avoid
+- Example: "DO NOT say: 'I'll note it for the team', 'I can take responsibility', etc."
+
+**Avoid overfitting:**
+- ❌ Never use specific person names ("Lindy", "Sarah")
+- ✅ Use generic examples ("a person", "someone coordinating")
+- ✅ Use placeholder variables when possible
+
+**BAML Update Checklist:**
+- [ ] No specific person names (generic examples only)
+- [ ] Explicit instructions (NEVER, CRITICAL, MUST NOT)
+- [ ] Multiple relevant sections updated if needed
+- [ ] Banned phrases listed explicitly
+- [ ] Examples provided (correct and incorrect)
+- [ ] Regenerated BAML client (`npm run generate`)
+
+## RULE 5: Iterative Refinement
+
+### For Complex Rule Updates
+
+**Start with core rule:**
+- Add basic rule first
+- Test to see if it works
+
+**Test edge cases:**
+- Identify problematic phrases/behaviors
+- Look for variations of the issue
+
+**Iterate:**
+- Add specific exceptions and banned phrases
+- Refine based on user feedback
+
+**Regenerate and verify:**
+- Always run `npm run generate` after changes
+- Check for lint errors (note pre-existing vs new)
+
+**Refinement Checklist:**
+- [ ] Core rule added
+- [ ] Edge cases identified
+- [ ] Specific exceptions added
+- [ ] BAML client regenerated
+- [ ] Lint errors checked
+
+## RULE 6: Minimal Fixes Strategy
+
+### When Implementing Fixes
+
+**Focus on root cause:**
+- Don't fix symptoms, fix the underlying issue
+- Example: Don't add workarounds, fix the prompt logic
+
+**Smallest change:**
+- Make the minimal change that solves the problem
+- Avoid over-engineering
+
+**Multiple locations if needed:**
+- If issue appears in multiple places, fix all instances
+- Don't partially fix
+
+**Don't over-engineer:**
+- Avoid adding complex logic when simple rule updates work
+- Example: Adding validation code when prompt instruction works
+
+**Minimal Fix Checklist:**
+- [ ] Root cause identified (not just symptom)
+- [ ] Smallest possible change made
+- [ ] All instances fixed if issue appears multiple times
+- [ ] No unnecessary complexity added
+
+## RULE 7: Documentation
+
+### After Analysis
+
+**Create analysis document:**
+- Document findings, patterns, and recommendations
+- Include specific examples from records
+- Link to source data
+
+**Create GitHub issues:**
+- For gaps that can't be fixed immediately (preferences)
+- Include clear recommendations and implementation points
+- Label appropriately (enhancement, area:preferences, etc.)
+
+**Link to analysis:**
+- Reference source documents in issues and code comments
+- Include record IDs for traceability
+
+**Record patterns:**
+- Document patterns for future reference
+- Note what worked and what didn't
+
+**Documentation Checklist:**
+- [ ] Analysis document created with findings
+- [ ] GitHub issues created for preference gaps
+- [ ] Source documents linked
+- [ ] Patterns documented for future reference
+
+## RULE 8: Testing & Validation
+
+### Before Considering Fixes Complete
+
+**Regenerate BAML client:**
+- Always run `npm run generate` after BAML changes
+- Verify generation succeeds
+
+**Check lint errors:**
+- Verify no new errors introduced
+- Note any pre-existing errors (don't fix unrelated issues)
+
+**Verify changes:**
+- Confirm changes are in correct locations
+- Check that all relevant sections updated
+
+**Don't commit prematurely:**
+- User may request multiple iterations
+- Wait for explicit commit instruction
+
+**Testing Checklist:**
+- [ ] BAML client regenerated (`npm run generate`)
+- [ ] Lint errors checked (no new errors)
+- [ ] Changes verified in correct locations
+- [ ] Not committed (wait for user instruction)
+
+## COMMON PATTERNS
+
+### Pattern 1: Time Window Preferences
+**Issue**: "Executive prefers not to have 6-7pm meetings"  
+**Solution**: Use focus blocks with HIGH protection (don't add new field)  
+**Implementation**: Create focus block for 6-7pm with `protection_level: HIGH`
+
+### Pattern 2: Location Defaults
+**Issue**: "Location incorrectly defaulted to virtual when should be in-person"  
+**Solution**: Add `default_meeting_location_type` to ExecutivePreferences  
+**Implementation**: New field in schema, use in BAML when location not specified
+
+### Pattern 3: Accountability Violations
+**Issue**: "Ashley took over coordination when someone else was coordinating"  
+**Solution**: Add explicit rules to respect existing accountability  
+**Implementation**: Update AccountabilityRules template, add banned phrases list
+
+### Pattern 4: Date Interpretation Errors
+**Issue**: "This week included past dates"  
+**Solution**: Add validation rules to never include past dates  
+**Implementation**: Update date interpretation rules in calendar_intent.baml
+
+## ANTI-PATTERNS TO AVOID
+
+1. **❌ Adding new fields when focus blocks work**: Use existing infrastructure first
+2. **❌ Using specific names in prompts**: Always use generic examples
+3. **❌ Fixing symptoms not root causes**: Dig deeper to find underlying issue
+4. **❌ Over-engineering solutions**: Simple prompt updates often work better than complex logic
+5. **❌ Skipping categorization**: Always categorize before fixing
+
+## RELATED RULES
+
+- `get_fraim_file({ path: "rules/successful-debugging-patterns.md" })` - General debugging patterns
+- `get_fraim_file({ path: "rules/code-quality-and-debugging-patterns.md" })` - Code quality standards
+- `get_fraim_file({ path: "rules/ashley-architecture.md" })` - BAML architecture guidelines
+
+## EXAMPLES
+
+### Good: Systematic Analysis
+```
+1. Query PPE database with proper filters
+2. Identify 18 records with reviewer feedback
+3. Categorize: 7 systemic, 3 preferences
+4. Fix systemic issues in BAML
+5. Create GitHub issue for preferences
+6. Document in retrospective
+```
+
+### Bad: Ad-hoc Fixes
+```
+1. See one issue
+2. Fix it immediately
+3. Don't check for patterns
+4. Don't categorize
+5. Don't document
+```
+
+---
+
+**Source**: Derived from retrospective `retrospectives/ppe-hitl-feedback-analysis-debugging-patterns.mdc`  
+**Last Updated**: 2025-11-05

package/registry/rules/local-development.md

@@ -19,7 +19,7 @@ Enable safe parallel development through strict workspace separation, preventing
 All your work **MUST** be in your folder.
 - Coordinate with other agents through GitHub issues and PRs
 - Each agent works independently in their own folder to enable true parallel development
-- Run every command using `npx tsx .ai-agents/scripts/exec-with-timeout.ts --timeout 30 -- <your command>` to prevent hangs in the terminal. You can adjust the timeout if the task is expected to run longer, but always have a timeout.
+- Run every command using `npx tsx ~/.fraim/scripts/exec-with-timeout.ts --timeout 30 -- <your command>` (Script is pre-synced)
 
 ## CRITICAL RULE: Absolute Workspace Separation
 
@@ -70,13 +70,15 @@ ALL commands must use the timeout wrapper:
 
 ```bash
 # Standard timeout (30 seconds)
-npx tsx .ai-agents/scripts/exec-with-timeout.ts --timeout 30 -- npm install
+npx tsx ~/.fraim/scripts/exec-with-timeout.ts --timeout 30 -- npm install
 
 # Extended timeout for long operations
-npx tsx .ai-agents/scripts/exec-with-timeout.ts --timeout 300 -- npm run build
+npx tsx ~/.fraim/scripts/exec-with-timeout.ts --timeout 300 -- npm run build
 
 # Very long operations (tests, servers)
-npx tsx .ai-agents/scripts/exec-with-timeout.ts --timeout 1800 -- npm run test-all
+npx tsx ~/.fraim/scripts/exec-with-timeout.ts --timeout 1800 -- npm run test-all
+
+# On Windows, use %USERPROFILE% instead of ~
 ```
 
 ### Timeout Guidelines
@@ -193,7 +195,7 @@ if (updateCall.request.resourceId !== expectedId) throw new Error('Wrong resourc
 ✅ File Operation: edit_file("src/api-service.ts")
 ✅ Branch Check: feature/84-fix-api-sync
 ✅ Path Verification: Relative path, no "../" patterns
-✅ Command: npx tsx .ai-agents/scripts/exec-with-timeout.ts --timeout 30 -- npm test
+✅ Command: npx tsx scripts/exec-with-timeout.ts --timeout 30 -- npm test
 ```
 
 ### Bad: Workspace Violations