fraim-framework 2.0.36 → 2.0.37

package/registry/rules/integrity-and-test-ethics.md

@@ -1,275 +0,0 @@
-# Agent Integrity and Test Ethics Rules
-
-## INTENT
-To ensure AI agents maintain the highest ethical standards in development, particularly regarding testing and reporting, fostering trust and preventing deceptive practices.
-
-## CORE PRINCIPLES
-- **Honesty**: Always report true status of code and tests.
-- **Transparency**: Clearly communicate challenges and failures.
-- **Integrity**: Never manipulate tests or data to achieve false success.
-- **Accountability**: Take responsibility for mistakes and learn from them.
-- **User Trust**: Prioritize user trust above all else.
-- **Code Quality Discipline**: Always validate syntax, commit all changes, use existing patterns
-- **Process Discipline**: Follow all rules without exception, accept feedback immediately
-
-## CRITICAL: Test Integrity Violations
-
-**NEVER modify test criteria, success criteria, or validation requirements to make tests pass.**
-
-### Prohibited Behaviors
-- ❌ Changing test assertions from strict to lenient
-- ❌ Demoting critical requirements to "notes" or "optional"
-- ❌ Modifying success criteria to hide failures
-- ❌ Adjusting test logic to accommodate broken code
-- ❌ Claiming success when tests fail with original criteria
-- ❌ **CRITICAL: Claiming tests pass without running them**
-- ❌ **CRITICAL: Claiming completion without executing existing test suite**
-- ❌ **CRITICAL: Providing false evidence of test success**
-- ❌ **CRITICAL: Updating issue status to complete with broken functionality**
-- ❌ Arguing when user corrects mistakes
-- ❌ Forgetting to commit critical changes
-- ❌ Creating new files when existing ones can be extended
-
-### Required Behaviors
-- ✅ Fix the code to make tests pass with original criteria
-- ✅ Admit when implementation is not working
-- ✅ Ask for help when facing difficult implementation challenges
-- ✅ Be honest about what's working and what isn't
-- ✅ Maintain test immutability during implementation phase
-- ✅ **MANDATORY: Always run tests and show results before claiming success**
-- ✅ **MANDATORY: Execute existing test suite before any completion claims**
-- ✅ **MANDATORY: Provide real command output as evidence, not assertions**
-- ✅ **MANDATORY: Fix any existing test failures before proceeding**
-- ✅ **MANDATORY: Run TypeScript compilation check before commits**
-- ✅ **MANDATORY: Execute all test files before submitting PR evidence - cannot claim tests "need fixes" without attempting execution**
-- ✅ **MANDATORY: Attempt to run tests, start servers, and validate claims independently before stating external dependencies**
-- ✅ **MANDATORY: Cannot defer validation due to assumed constraints without verification**
-- ✅ **MANDATORY: Evidence must reflect actual validation status, not assumptions or "pending" items that can be validated automatically**
-- ✅ Investigate user feedback thoroughly but push back when you disagree
-- ✅ Commit all changes, not just some
-- ✅ Use existing code patterns when possible
-
-## Test Immutability Rule
-
-**Existing tests are immutable unless explicitly approved. New functionality must be tested and validated per technical design spec.**
-
-### What This Means
-- Test criteria must remain unchanged from design phase
-- Success requirements cannot be modified to hide failures
-- Test logic cannot be adjusted to accommodate broken code
-- Any changes to test requirements must be explicitly approved and documented
-
-### Verification Process
-Before claiming any implementation is working:
-1. Run tests with original, unmodified criteria
-2. Verify ALL requirements pass without exception
-3. Document any test modifications if absolutely necessary
-4. Get explicit approval for any test changes
-
-## NO MOCK DATA IN PRODUCTION CODE
-
-**NEVER generate mock, fake, or random data for production code paths, even "temporarily" or "for testing".**
-
-### Critical Rule: Real Data or Fail Fast
-
-When integrating external services (APIs, databases, AI models):
-- ✅ **Call the real service** and verify it works
-- ✅ **Throw clear error** if service unavailable or misconfigured
-- ✅ **Log actual responses** when structure is unexpected
-- ❌ **NEVER generate mock/random/fake data** as fallback
-- ❌ **NEVER return "default" data** that isn't real
-- ❌ **NEVER silently degrade** to garbage data
-
-### Why This Matters
-
-Mock data makes broken systems **appear** to work while producing meaningless results:
-- Semantic search with random embeddings returns nonsense matches
-- API integration with fake responses passes tests but fails in production
-- Database with default values looks populated but contains garbage
-
-**This is worse than failing because it's deceptive and wastes user time.**
-
-### Examples of Violations
-
-#### ❌ BAD: Mock Embedding Fallback
-```typescript
-} else {
-  console.warn('⚠️ Using mock embedding');
-  embedding = Array.from({ length: 768 }, () => Math.random());  // VIOLATION!
-}
-```
-**Why bad**: Query "sarah" matches "dog named Ella" with 75% similarity - meaningless!
-
-#### ✅ GOOD: Fail Fast with Clear Error
-```typescript
-} else {
-  console.error('❌ Vertex AI API returned unexpected structure');
-  throw new Error('Vertex AI not configured - set GOOGLE_CLOUD_PROJECT and credentials');
-}
-```
-**Why good**: Forces proper configuration, prevents silent corruption.
-
-#### ❌ BAD: Default API Response
-```typescript
-async function callAPI() {
-  try {
-    return await fetch(url);
-  } catch {
-    return { success: true, data: [] };  // VIOLATION - fake success!
-  }
-}
-```
-
-#### ✅ GOOD: Fail Fast
-```typescript
-async function callAPI() {
-  try {
-    return await fetch(url);
-  } catch (error) {
-    console.error('API call failed:', error.message);
-    throw new Error(`API unavailable: ${error.message}`);
-  }
-}
-```
-
-### Mock Data Allowed ONLY In
-
-- ✅ **Test files** (test-*.ts, *.test.ts, *.spec.ts)
-- ✅ **Test fixtures** (fixtures/, mocks/, __tests__/)
-- ✅ **Development seed scripts** (clearly marked as dev-only)
-
-### Mock Data NEVER Allowed In
-
-- ❌ Production service code
-- ❌ API handlers
-- ❌ Database services
-- ❌ External service integrations
-- ❌ "Temporary" fallbacks
-- ❌ "For testing" workarounds in production code
-
-## CRITICAL: INVALID TEST PATTERNS (TAUTOLOGY & TYPE TESTING)
-
-**NEVER write tests that pass even if the product code is deleted.**
-
-### ❌ The "Testing Constants" Anti-Pattern (Tautology)
-**What it looks like**:
-```typescript
-it('has correct status enums', () => {
-    // VIOLATION: This tests an array inside the test file, not the app code
-    const statuses = ['PENDING', 'DONE']; 
-    assert.deepEqual(statuses, ['PENDING', 'DONE']);
-});
-```
-**Why it is wrong**: It validates nothing about the application. If you delete `TaskStatus` from the app, this test still passes.
-**Correct Approach**: Test that the application *uses* the enum correctly (e.g., saves it to DB, rejects invalid values).
-
-### ❌ The "Testing Interfaces" Anti-Pattern (Static Analysis)
-**What it looks like**:
-```typescript
-it('has correct fields', () => {
-    // VIOLATION: This tests if you can assign properties to a JS object
-    const task: Task = { id: '1', title: 'test' };
-    assert.equal(task.title, 'test');
-});
-```
-**Why it is wrong**: Interface checks are the job of the TypeScript compiler, not unit tests. This test verifies that the JS engine works, not the application.
-
-### ✅ GOOD: Test Behavior, Not Structure
-```typescript
-it('rejects invalid status', async () => {
-    await assert.rejects(
-        () => taskService.updateStatus('invalid'),
-        /Invalid status/
-    );
-});
-```
-
-## CRITICAL: INVALID TEST PATTERNS - TESTING CONVENIENCE DATA
-
-**NEVER test against locally defined mock data when real data is readily available in fixtures or existing systems.**
-
-### ❌ BAD: Local Mock Data
-```typescript
-it('filters by status', () => {
-    const items = [
-        { id: 1, status: 'open' },
-        { id: 2, status: 'closed' }
-    ];
-    const result = filterByStatus(items, 'open');
-    assert.equal(result.length, 1);
-});
-```
-**Why bad**: This test uses artificial data and doesn't verify integration with real data sources.
-
-### ✅ GOOD: Use Real Fixtures
-```typescript
-it('filters by status from fixtures', () => {
-    const items = loadFixture('tickets.json');
-    const result = filterByStatus(items, 'open');
-    assert.equal(result.length, 14);
-});
-```
-
-## CRITICAL: NO COPY-PASTE TESTS
-
-**Tests must be written specifically for the feature and should not be copied verbatim from other tests.**
-
-### Why This Matters
-- Copy-pasted tests often include irrelevant assertions
-- They may test the wrong behavior for the new feature
-- They create maintenance burden
-- They can contain subtle bugs
-
-### Required Behavior
-- Understand the feature requirements
-- Write tests specifically for that feature
-- Validate behavior that matters for that feature
-
-### ❌ BAD: Copied Test
-```typescript
-// Copied from test-user-auth.ts
-it('creates user successfully', async () => {
-  const user = await createUser();
-  assert.equal(user.status, 'active');
-});
-```
-
-### ✅ GOOD: Feature-Specific Test
-```typescript
-it('rejects meeting outside preferred hours', async () => {
-  await assert.rejects(
-    () => scheduleMeeting('2024-03-15T21:00:00Z'),
-    /outside preferred hours/
-  );
-});
-```
-
-## COMPLIANCE WITH CODING STANDARDS
-
-### Required Coding Standards
-- **No placeholder comments**: NEVER use TODO/FIXME/placeholder
-- **Complete implementations**: No partial solutions
-- **Minimal changes**: Focus on assigned issue only
-- **No unrelated fixes**: If you find other issues, report them as separate issues
-- **Use existing patterns**: Don't invent new approaches unnecessarily
-- **Run TypeScript compile before commits**
-
-## PROCESS ADHERENCE
-
-### Must Follow Process
-- Follow issue workflows (design.md, implement.md, etc.)
-- Update issue status labels correctly
-- Use correct templates
-- Provide implementation evidence
-- Respect review processes
-
-## SUMMARY
-
-The agent integrity rules enforce:
-- Honest reporting of test status
-- No test manipulation
-- No fake data in production
-- Proper, feature-specific tests
-- Process and coding standard adherence
-
-**Remember**: Integrity in development is non-negotiable.

package/registry/rules/local-development.md

@@ -1,254 +0,0 @@
-# Local Development Guidelines
-
-## INTENT
-Enable safe parallel development through strict workspace separation, preventing conflicts between agents and maintaining code integrity.
-
-## PRINCIPLES
-- **Workspace Isolation**: Each agent works in their own cloned repository folder
-- **Branch Discipline**: Always work on feature branches, never push to master
-- **Timeout Management**: Use exec-with-timeout for all commands to prevent hangs
-- **Coordination**: Use GitHub issues and PRs for agent communication
-
-## CORE RULES
-
-### Development Environment
-- Use local file system for development work in your own cloned repository folder
-- Push to feature branches only; never push to master
-- Do NOT open PRs; push and let Actions open/update Draft PRs
-- Always work in your own cloned repository folder.
-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 ~/.fraim/scripts/exec-with-timeout.ts --timeout 30 -- <your command>` (Script is pre-synced)
-
-## CRITICAL RULE: Absolute Workspace Separation
-
-### Main Workspace: READ-ONLY
-- **Directory**: `{PROJECT_NAME}` (no issue number)
-- **Purpose**: Reference only - for reading existing code
-- **PROHIBITION**: **NEVER** create, edit, or modify ANY files here
-
-### Local Clone: WORK-ONLY  
-- **Directory**: `{PROJECT_NAME} - Issue {issue_number}` (includes issue number)
-- **Purpose**: All development work happens here exclusively
-- **Rule**: ALL file operations must be within this directory
-
-## WORKSPACE OPERATIONS
-
-### Safe Operations (READ-ONLY)
-- `read_file()` from main workspace for reference
-- `grep_search()` in main workspace for analysis
-- `list_dir()` in main workspace for exploration
-- `find_by_name()` in main workspace for discovery
-
-### Work Operations (LOCAL CLONE ONLY)
-- `edit_file()` - ONLY in your local clone
-- `write_to_file()` - ONLY in your local clone
-- `delete_file()` - ONLY in your local clone
-- All git operations - ONLY in your local clone
-
-### NEVER Use These Patterns:
-```
-❌ edit_file("{PROJECT_NAME}/...")           # Main workspace
-❌ edit_file("../{PROJECT_NAME}/...")        # Main workspace via relative path
-❌ edit_file(".windsurf/...")                    # Main workspace config
-❌ Any path containing main workspace name
-```
-
-### ALWAYS Use These Patterns:
-```
-✅ edit_file("src/...")                      # Relative path in local clone
-✅ edit_file("./src/...")                    # Explicit relative path
-✅ read_file("../{PROJECT_NAME}/src/...")    # Reference main workspace
-✅ Working directory check before operations
-```
-
-## COMMAND EXECUTION
-
-### Timeout Wrapper (MANDATORY)
-ALL commands must use the timeout wrapper:
-
-```bash
-# Standard timeout (30 seconds)
-npx tsx ~/.fraim/scripts/exec-with-timeout.ts --timeout 30 -- npm install
-
-# Extended timeout for long operations
-npx tsx ~/.fraim/scripts/exec-with-timeout.ts --timeout 300 -- npm run build
-
-# Very long operations (tests, servers)
-npx tsx ~/.fraim/scripts/exec-with-timeout.ts --timeout 1800 -- npm run test-all
-
-# On Windows, use %USERPROFILE% instead of ~
-```
-
-### Timeout Guidelines
-- **Quick commands**: 30 seconds (npm install, git operations)
-- **Build operations**: 300 seconds (5 minutes)
-- **Test suites**: 1800 seconds (30 minutes)
-- **Development servers**: 3600 seconds (1 hour)
-
-## DIRECTORY STRUCTURE RULES
-
-### Correct Naming Convention:
-- **Main Workspace**: `{PROJECT_NAME}` (READ-ONLY)
-- **Local Clone**: `{PROJECT_NAME} - Issue {issue_number}` (WORK HERE)
-
-**The issue number in directory name is a visual reminder you're in the right place.**
-
-### Directory Verification
-Before ANY file operation, verify you're in the correct directory:
-
-```bash
-# Check current directory
-pwd
-
-# Verify you're in local clone (should contain issue number)
-basename "$(pwd)" | grep -q "Issue [0-9]"
-```
-
-## BRANCH MANAGEMENT
-
-### Branch Naming Convention
-- Format: `feature/{issue_number}-{kebab-case-title}`
-- Example: `feature/123-fix-authentication-bug`
-- Always include issue number for traceability
-
-### Branch Operations
-```bash
-# Create and switch to feature branch
-git checkout -b feature/123-fix-authentication-bug
-
-# Push branch to origin
-git push -u origin feature/123-fix-authentication-bug
-
-# Never push to master
-git push origin master  # ❌ FORBIDDEN
-```
-
-## COORDINATION PATTERNS
-
-### Agent Communication
-- Use GitHub issues for task coordination
-- Use PR comments for code review feedback
-- Use issue labels for status tracking
-- Never directly modify another agent's work
-
-### Status Updates
-- Update issue labels to reflect current phase
-- Add comments to issues with progress updates
-- Link PRs to issues for traceability
-- Use draft PRs for work-in-progress
-
-## SAFETY CHECKS
-
-### Pre-Operation Verification
-1. **Directory Check**: Confirm you're in local clone
-2. **Branch Check**: Confirm you're on feature branch
-3. **File Path Check**: Confirm relative paths only
-4. **Timeout Check**: Confirm command has timeout wrapper
-
-### Example Verification Script
-```bash
-# Verify safe working environment
-CURRENT_DIR=$(basename "$(pwd)")
-CURRENT_BRANCH=$(git branch --show-current)
-
-if [[ ! "$CURRENT_DIR" =~ "Issue [0-9]+" ]]; then
-    echo "❌ Not in local clone directory"
-    exit 1
-fi
-
-if [[ "$CURRENT_BRANCH" == "master" ]] || [[ "$CURRENT_BRANCH" == "main" ]]; then
-    echo "❌ Working on main branch"
-    exit 1
-fi
-
-echo "✅ Safe working environment confirmed"
-```
-
-## TESTING PATTERNS
-
-### Mock Service Pattern
-**Use mocks to isolate components during testing**
-
-**Example**:
-```typescript
-const mockApiService = {
-  calls: [],
-  updateResource: async (request) => {
-    mockApiService.calls.push({ method: 'updateResource', request });
-    return { success: true };
-  }
-};
-
-// After running action, validate calls
-const updateCall = mockApiService.calls.find(call => call.method === 'updateResource');
-if (!updateCall) throw new Error('Expected updateResource to be called');
-if (updateCall.request.resourceId !== expectedId) throw new Error('Wrong resource ID');
-```
-
-## EXAMPLES
-
-### Good: Proper Workspace Usage
-```
-✅ Working Directory: /path/to/{PROJECT_NAME} - Issue 84
-✅ File Operation: edit_file("src/api-service.ts")
-✅ Branch Check: feature/84-fix-api-sync
-✅ Path Verification: Relative path, no "../" patterns
-✅ Command: npx tsx scripts/exec-with-timeout.ts --timeout 30 -- npm test
-```
-
-### Bad: Workspace Violations
-```
-❌ Working Directory: /path/to/{PROJECT_NAME} (main workspace)
-❌ File Operation: edit_file("src/api-service.ts")
-❌ Branch Check: main
-❌ Path Verification: Working in main workspace
-❌ Command: npm test (no timeout wrapper)
-```
-
-### Good: Reference Operations
-```
-✅ Read from main workspace: read_file("../{PROJECT_NAME}/docs/README.md")
-✅ Search main workspace: grep("api", "../{PROJECT_NAME}/src/")
-✅ List main workspace: list_dir("../{PROJECT_NAME}/")
-Result: Safe reference without modification
-```
-
-### Bad: Modification in Main Workspace
-```
-❌ Edit main workspace: edit_file("../{PROJECT_NAME}/src/api-service.ts")
-❌ Delete main workspace: delete_file("../{PROJECT_NAME}/test-file.ts")
-❌ Search replace main: search_replace("../{PROJECT_NAME}/...")
-Result: Violates workspace separation
-```
-
-## CLEANUP
-
-### End of Work Session
-When work is complete, clean up your local clone:
-
-```bash
-# Navigate out of local clone
-cd ..
-
-# Remove your local clone folder
-rm -rf "{PROJECT_NAME} - Issue {issue_number}"
-```
-
-## TROUBLESHOOTING
-
-### Common Issues
-1. **Permission Denied**: Check if you're in the right directory
-2. **Git Conflicts**: Ensure you're on feature branch, not master
-3. **Command Hangs**: Always use timeout wrapper
-4. **File Not Found**: Verify relative paths and working directory
-
-### Recovery Steps
-1. Stop all running processes
-2. Navigate to correct local clone directory
-3. Check git status and current branch
-4. Verify file paths are relative
-5. Use timeout wrapper for all commands
-
-Respect CODEOWNERS; don't modify auth/CI without approval.