fraim-framework 2.0.55 → 2.0.57

package/dist/registry/ai-manager-rules/implement-phases/implement-regression.md

@@ -1,173 +0,0 @@
-# Phase: Regression
-
-## INTENT
-For bugs: Verify the repro test now passes. For features: Write comprehensive regression tests to prevent future breakage.
-
-## OUTCOME
-**For Bugs:**
-- Repro test from implement-repro phase now PASSES
-- Bug is confirmed fixed
-- Test serves as regression protection
-
-**For Features:**
-- New regression tests written
-- All key functionality covered
-- Tests verify acceptance criteria
-- All tests pass
-
-**Note**: This phase focuses specifically on regression testing. Build validation and manual testing are handled in other phases.
-
-## PRINCIPLES
-- **Test Quality**: Write meaningful tests, not checkbox tests
-- **Coverage**: Test main scenarios and edge cases
-- **Real Testing**: Test actual functionality, not mocks
-- **Maintainable**: Tests should be clear and maintainable
-
-## WORKFLOW
-
-### For Bug Fixes:
-
-#### Step 1: Run Repro Test
-```bash
-npm test -- path/to/repro/test.test.ts
-```
-
-#### Step 2: Verify Test Passes
-- Test should now PASS (was failing in implement-repro phase)
-- Confirms bug is fixed
-- Test serves as regression protection
-
-#### Step 3: If Test Still Fails
-**Return to implement phase:**
-- Bug is not actually fixed
-- Review the fix
-- Debug why test still fails
-- Fix and re-validate
-
-### For Features:
-
-#### Step 1: Identify Test Coverage Needed
-Based on acceptance criteria:
-- Main user scenarios
-- Edge cases
-- Error conditions
-- Integration points
-
-#### Step 2: Write Regression Tests
-- Create tests for all key functionality
-- Test main user workflows
-- Cover edge cases
-- Test error handling
-
-#### Step 3: Follow Test Architecture
-Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then read the local architecture document to understand the full architecture guidelines. Key requirements:
-- Use shared-server-utils.ts
-- Unique API keys per test
-- Proper cleanup in finally blocks
-- No individual server instances
-- Proper timeouts (5-10s for network calls)
-
-#### Step 4: Run All New Tests
-```bash
-npm test -- path/to/new/tests.test.ts
-```
-
-Verify all tests pass
-
-#### Step 5: Tag Tests Appropriately
-- `smoke`: If testing core functionality
-- `integration`: If testing multiple components
-- `unit`: If testing individual functions
-- `e2e`: If testing complete workflows
-
-## VALIDATION
-
-### Phase Complete When:
-
-**For Bugs:**
-- ✅ Repro test now PASSES
-- ✅ Bug confirmed fixed
-- ✅ Test output documented
-
-**For Features:**
-- ✅ Regression tests written
-- ✅ All acceptance criteria covered
-- ✅ Tests follow architecture standards
-- ✅ All tests pass
-- ✅ Tests appropriately tagged
-
-### Phase Incomplete If:
-- ❌ (Bugs) Repro test still fails
-- ❌ (Features) No regression tests written
-- ❌ (Features) Tests don't cover acceptance criteria
-- ❌ Any tests fail
-- ❌ Tests violate architecture standards
-
-## RULES FOR THIS PHASE
-- Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then read the local architecture document to understand the full test architecture guidelines
-- Use Successful Debugging Patterns from `rules/successful-debugging-patterns.md` via `get_fraim_file`
-- Follow Git Safe Commands from `rules/git-safe-commands.md` via `get_fraim_file`
-
-### Failure Handling
-- **If regression tests fail**: Return to implement-code phase
-- **If test writing fails**: Return to implement-code phase to understand implementation better
-- Fix the implementation first, then write proper regression tests
-
-## TEST QUALITY REQUIREMENTS
-- Tests must validate real functionality, not mocked behavior
-- No tests that default to passing without validation
-- Use flow testing, not just static analysis
-- Tests should fail if code is broken
-
-## SCRIPTS
-
-**Run tests:**
-```bash
-npm test -- path/to/test.test.ts
-```
-
-**Run all tests:**
-```bash
-npm test
-```
-
-### Report Back (Bugs):
-When you complete this phase for a bug fix, call:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-regression", 
-  status: "complete",
-  findings: {
-    issueType: "bug" // Required for phase validation
-  },
-  evidence: {
-    reproTestResult: "Repro test at test/sync.test.ts:45 now PASSES",
-    bugStatus: "Bug confirmed fixed",
-    regressionProtection: "Test serves as regression protection"
-  }
-})
-```
-
-### Report Back (Features):
-When you complete this phase for a feature, call:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-regression", 
-  status: "complete",
-  findings: {
-    issueType: "feature" // Required for phase validation
-  },
-  evidence: {
-    testLocation: "test/auth.test.ts",
-    testCoverage: "All acceptance criteria covered",
-    testResults: "8/8 tests passing",
-    testTags: "Tagged as integration"
-  }
-})
-```

package/dist/registry/ai-manager-rules/implement-phases/implement-repro.md

@@ -1,104 +0,0 @@
-# Phase: Implement-Repro
-
-## INTENT
-To create a failing test that reproduces the reported bug, demonstrating that the issue exists and providing a clear success criterion for the fix.
-
-## OUTCOME
-A test that:
-- **FAILS** when run, reproducing the bug
-- Clearly demonstrates the incorrect behavior
-- Will pass once the bug is fixed
-- Serves as a regression test
-
-## PRINCIPLES
-- **Test-First**: Create the failing test before fixing
-- **Actual Reproduction**: Use real reproduction, not hypothetical scenarios
-- **Clear Failure**: Test should fail obviously and consistently
-- **No Assumptions**: If reproduction steps are unclear, escalate to user
-- **Minimal Test**: Focus on reproducing the specific bug
-
-## WORKFLOW
-
-### Step 1: Review Bug Spec
-- Read the bug description thoroughly
-- Note the reproduction steps
-- Understand the expected vs actual behavior
-- Identify the failure conditions
-
-### Step 2: Check Reproduction Steps
-**If reproduction steps are clear:**
-- Proceed to create test
-
-**If reproduction steps are unclear or missing:**
-- **DO NOT** hypothesize about the issue
-- **ESCALATE** to user with specific questions:
-  - What exact steps trigger the bug?
-  - What is the expected behavior?
-  - What is the actual (incorrect) behavior?
-  - Are there specific inputs or conditions?
-
-### Step 3: Create Failing Test
-- Choose appropriate test file location
-- Write test that follows reproduction steps
-- Test should demonstrate the bug clearly
-- Use descriptive test name: `test: reproduces bug #{issue_number} - {description}`
-
-### Step 4: Run the Test
-- Execute the test
-- **Verify it FAILS** as expected
-- Capture the failure output
-- Confirm it fails for the right reason (reproducing the bug, not test errors)
-
-### Step 5: Document Test Location
-In your evidence, include:
-- Path to the test file
-- Test name/description
-- Failure output showing the bug
-- Confirmation that test reproduces the issue
-
-## VALIDATION
-
-### Phase Complete When:
-- ✅ Test created that reproduces the bug
-- ✅ Test FAILS when run
-- ✅ Failure clearly demonstrates the bug
-- ✅ Test will pass once bug is fixed
-- ✅ Test location documented
-
-### Phase Incomplete If:
-- ❌ Test passes (not reproducing the bug)
-- ❌ Test fails for wrong reason (test error, not bug)
-- ❌ Reproduction steps were unclear and not escalated
-- ❌ Test is hypothetical, not based on actual reproduction
-
-## RULES FOR THIS PHASE
-- Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then read the local architecture document to understand the full test architecture standards
-- Use Successful Debugging Patterns from `rules/successful-debugging-patterns.md` via `get_fraim_file`
-- Follow Git Safe Commands from `rules/git-safe-commands.md` via `get_fraim_file`
-
-## SCRIPTS
-Run test:
-```bash
-npm test -- path/to/test/file.test.ts
-```
-
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-repro", 
-  status: "complete",
-  findings: {
-    issueType: "bug" // Required for phase validation
-  },
-  evidence: {
-    testLocation: "test/sync.test.ts:45",
-    testResult: "FAILS with timeout after 30s",
-    reproductionConfirmed: true,
-    testOutput: "Include actual test failure output here"
-  }
-})
-```

package/dist/registry/ai-manager-rules/implement-phases/implement-scoping.md

@@ -1,100 +0,0 @@
-# Phase: Implement-Scoping
-
-## INTENT
-To understand the issue requirements and determine whether it's a bug fix or feature implementation.
-
-## OUTCOME
-Clear understanding of:
-- Issue type (bug or feature)
-- All requirements and acceptance criteria
-- Ready to proceed to next phase (repro for bugs, spike for features)
-
-## PRINCIPLES
-- **Thorough Understanding**: Read all linked documents and context
-- **Clear Classification**: Accurately determine bug vs feature
-- **Question Early**: Escalate if requirements are unclear
-
-## RULES FOR THIS PHASE
-
-### Success Criteria
-Read `registry/rules/agent-success-criteria.md` via `get_fraim_file` for the complete 5-criteria success framework. Focus especially on **Integrity** (truthfulness in reporting) and **Independence** (smart decision making).
-
-### Simplicity Principles  
-Read `registry/rules/simplicity.md` via `get_fraim_file` for complete guidelines. Key principles for scoping:
-- **Focus on the assigned issue only** - don't scope other issues
-- **Don't over-think it** - understand the specific need being addressed
-
-### Architecture Compliance
-Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then read the local architecture document to understand the full architecture guidelines. Understanding the architecture helps with proper scoping.
-
-## WORKFLOW
-
-### Step 1: Get Repository Context and Issue Details
-
-**GitHub Repository Context**: Before using GitHub MCP tools, read the local `.fraim/config.json` file to get the repository context:
-- Use `git.repoOwner` for the GitHub repository owner
-- Use `git.repoName` for the GitHub repository name
-- These values are required for GitHub MCP API calls (owner/repo parameters)
-
-**Read Issue Details**: Use GitHub MCP tools to get the complete issue information:
-- Read the full issue description in GitHub (use MCP where available)
-- Note the issue title, labels, and any linked documents
-- Identify if there's a spec, RFC, or design document
-
-### Step 2: Review Linked Documents
-- If spec/RFC exists: Read it thoroughly
-- If design document exists: Review the technical approach
-- Note all acceptance criteria and requirements
-
-### Step 3: Determine Issue Type
-**Bug indicators:**
-- Issue describes broken/incorrect behavior
-- References a regression or failure
-- Has reproduction steps
-- Reports unexpected behavior
-
-**Feature indicators:**
-- Issue describes new functionality
-- Adds capabilities that don't exist
-- Enhances existing features
-- Has acceptance criteria for new behavior
-
-### Step 4: Understand Requirements
-- List all acceptance criteria
-- Identify edge cases mentioned
-- Note any constraints or limitations
-- Understand success criteria
-
-### Step 5: Identify Uncertainties
-If anything is unclear:
-- **DO NOT** make assumptions
-- **DO NOT** hypothesize requirements
-- **ESCALATE** to user with specific questions
-- Wait for clarification before proceeding
-
-## VALIDATION
-
-### Phase Complete When:
-- ✅ Issue type determined (bug or feature)
-- ✅ All requirements understood
-- ✅ No blocking uncertainties remain
-- ✅ Ready to proceed to next phase
-
-### Report Back:
-When you complete scoping, call:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-scoping", 
-  status: "complete",
-  findings: {
-    issueType: "bug", // or "feature"
-    requirements: "Brief summary of what you understood",
-    uncertainties: [] // List any unclear aspects, or empty array if none
-  }
-})
-```
-
-The AI Coach will provide instructions for your next phase based on the issue type you determined.

package/dist/registry/ai-manager-rules/implement-phases/implement-smoke.md

@@ -1,237 +0,0 @@
-# Phase: Implement-Smoke
-
-## INTENT
-To run technical health checks ensuring the system is stable: build passes, all tests pass, git status is clean, and core functionality hasn't been broken by the implementation.
-
-## OUTCOME
-All technical checks pass, confirming:
-- Build compiles successfully  
-- All tests pass (100% success rate)
-- Git status is clean
-- Core system functionality intact
-- No regressions in critical paths
-
-**Note**: This phase focuses purely on technical health checks. Manual validation and functional testing are handled in the implement-validate phase.
-
-## PRINCIPLES
-- **Zero Tolerance**: All checks must pass
-- **Technical Focus**: Automated verification only
-- **Fix Immediately**: If any check fails, return to implement phase
-- **Fast Feedback**: Quick automated verification
-
-## 📋 MANDATORY TECHNICAL CHECKS
-
-### Step 0: Read Project Validation Commands 📖
-
-**FIRST**: Check your project's custom commands:
-
-```bash
-# Check for custom build command
-cat .fraim/config.json | grep -A 3 "buildCommand"
-
-# Check for custom smoke test command  
-cat .fraim/config.json | grep -A 3 "smokeTestCommand"
-```
-
-**Use the configured commands if they exist, otherwise use the defaults shown below.**
-
-### Step 1: Build Compilation Check ✅
-
-**Requirements**:
-- TypeScript compiles without errors
-- Build process completes successfully
-- No type errors or warnings
-
-**Commands to Run** (use customizations.validation.buildCommand from config if available):
-```bash
-# Use project-specific build command from .fraim/config.json if available:
-# - Look for customizations.validation.buildCommand
-# - Use that command if available, otherwise default to:
-npm run build
-```
-
-**What to Look For**:
-- Exit code 0 (success) for all commands
-- No error messages in output
-- Clean compilation without warnings
-
-### Step 2: Complete Test Suite ✅
-
-**Requirements**:
-- ALL existing tests pass (100% success rate) - not just tests you created
-- No timeouts or hanging tests
-- Comprehensive test coverage validation
-
-**CRITICAL**: You must run the COMPLETE test suite, including all existing tests, smoke tests, and any tests you created. Do not run only the tests you wrote.
-
-**Commands to Run** (use customizations.validation.smokeTestCommand from config if available):
-```bash
-# Run the comprehensive test suite (use customizations.validation.smokeTestCommand if available)
-npm test
-```
-
-**What to Look For**:
-- "All tests passed" or similar success message
-- No "FAILED" or "ERROR" in output
-- Test count should include existing tests + any new tests you added
-- No timeout messages
-- Verify that existing functionality tests are included in the run
-
-**Example Expected Output**:
-```
-✅ Running 45 tests (including existing + new tests)
-✅ All tests passed
-✅ Test suite completed successfully
-```
-
-### Step 3: Git Status Check ✅
-
-**Requirements**:
-- Git status is clean
-- Only intended changes present
-- No untracked files (except evidence docs)
-
-**Commands to Run**:
-```bash
-# Check git status
-git status
-
-# Check recent commits
-git log --oneline -3
-```
-
-**What to Look For**:
-- Only intended files are modified
-- No accidentally modified files
-- Clean working directory
-- Meaningful commit messages
-
-### Step 4: Code Quality Verification ✅
-
-**Requirements**:
-- No type bypassing
-- No debugging code remains
-- No task placeholder comments in core functionality
-
-**Commands to Run**:
-```bash
-# Check for type bypassing
-grep -r "as any" src/ || echo "✅ No type bypassing found"
-
-# Look for debugging code
-grep -r "console.log" src/ | grep -v "logger" | grep -v "// OK" || echo "✅ No debug logs found"
-
-# Check for task placeholder comments
-grep -r "task-placeholder" src/ || echo "✅ No task placeholders found"
-```
-
-**What to Look For**:
-- Zero instances of "as any" (or only justified ones with comments)
-- No console.log statements (except intentional logging)
-- No task placeholder comments in critical code
-
-## 🛠️ TECHNICAL COMMANDS REFERENCE
-
-### Project-Specific Commands (Read from .fraim/config.json)
-```bash
-# Check your project's custom validation commands:
-cat .fraim/config.json | grep -A 5 "validation"
-```
-
-### Quick Health Check
-```bash
-# One-liner using project defaults (customize based on your config)
-npm run build && npm test && git status
-```
-
-## VALIDATION
-
-### Phase Complete When:
-- ✅ Build succeeds without errors
-- ✅ All tests pass (100% success rate)
-- ✅ Git status clean (only intended changes)
-- ✅ No "as any" type bypassing
-- ✅ No debugging code remains
-- ✅ No task placeholder comments in core functionality
-- ✅ All technical checks documented
-
-### Phase Incomplete If:
-- ❌ Build fails
-- ❌ ANY test fails
-- ❌ Git status shows unintended changes
-- ❌ Code quality issues found
-
-**If ANY check fails, return to implement-code phase immediately.**
-
-## RULES FOR THIS PHASE
-
-### Technical Standards
-- Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then read the local architecture document to understand the full technical standards
-- **Config Commands**: Always check `.fraim/config.json` first for `customizations.validation.buildCommand` and `customizations.validation.smokeTestCommand`, use those if available, otherwise use defaults
-- Use Successful Debugging Patterns from `rules/successful-debugging-patterns.md` via `get_fraim_file`
-- When using git commands directly (if MCP tools unavailable), read `rules/git-safe-commands.md` via `get_fraim_file`
-
-### Failure Handling
-- **If ANY technical check fails**: Return to implement-code phase
-- **Do not proceed to regression phase** if smoke tests fail
-- Fix the implementation first, then re-run smoke tests
-
-## SCRIPTS
-
-**Run all technical checks:**
-```bash
-npm run build && npm test && git status
-```
-
-**Run smoke tests specifically:**
-```bash
-# Use project-specific command from .fraim/config.json if available
-# Check: cat .fraim/config.json | grep "smokeTestCommand"
-# Use configured command or default to:
-npm run test-smoke-ci
-```
-
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-smoke", 
-  status: "complete",
-  findings: {
-    issueType: "bug" // or "feature" - Required for phase validation
-  },
-  evidence: {
-    buildPassed: "YES", // Did `npm run build` succeed?
-    allTestsPassed: "YES", // Did `npm test` show 100% pass rate?
-    gitStatusClean: "YES", // Does `git status` show only intended changes?
-    noTypeBypass: "YES", // Did `grep -r "as any" src/` find zero instances?
-    noDebugCode: "YES", // Did you remove console.log statements?
-    registryValid: "YES", // Did `npm run validate:registry` pass?
-    commandsRun: "npm run build && npm test && git status",
-    summary: "All technical checks passed. Build succeeds, all tests pass, git status clean."
-  }
-})
-```
-
-If any technical check fails:
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-smoke", 
-  status: "incomplete",
-  findings: {
-    issueType: "bug" // or "feature" - Required for phase validation
-  },
-  evidence: {
-    buildPassed: "NO", // Specify what failed
-    allTestsPassed: "NO", // Be specific about failures
-    issues: ["Build failed with TypeScript errors", "3 tests failing"],
-    commandsRun: "npm run build && npm test",
-    nextAction: "Returning to implement phase to fix technical issues"
-  }
-})
-```