fraim-framework 2.0.44 → 2.0.45

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

@@ -0,0 +1,371 @@
+# Phase: Implement-Validate
+
+## INTENT
+To verify that the implementation works correctly by testing it in appropriate ways: browser testing for UI changes, API testing for backend changes, and command-line testing for CLI changes.
+
+## OUTCOME
+Confirmation that:
+- Implementation works as expected
+- All acceptance criteria are met
+- Edge cases are handled
+- No obvious bugs or issues
+
+## 🎯 VALIDATION MINDSET
+
+This is THE critical phase where you prove your implementation actually works. No shortcuts, no assumptions.
+
+**Your Mission**: Prove beyond doubt that a real user can successfully use this feature.
+
+## RULES FOR THIS PHASE
+
+### Success Criteria
+Read `registry/rules/agent-success-criteria.md` via `get_fraim_file` for the complete framework. Focus on:
+- **Integrity** (honest reporting of validation results - never claim something works if you didn't test it)
+- **Correctness** (implementation actually works as expected)
+- **Completeness** (all acceptance criteria validated, edge cases tested)
+
+### Simplicity Principles
+Read `registry/rules/simplicity.md` via `get_fraim_file` for complete guidelines. Critical for validation:
+- **Manual Validation Required** - This is THE manual validation phase
+- **Prototype-First** - Validate the working solution before engineering tests
+- **Resource Waste Prevention** - Efficient testing approach
+
+### 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. Ensure implementation follows architectural patterns.
+
+### Debugging and Git Operations
+- 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` to avoid interactive commands that hang agents.
+
+### Failure Handling
+- **If validation fails**: Return to implement-code phase
+- **Do not proceed to smoke tests** if validation fails
+- Fix the implementation first, then re-validate
+
+## PRINCIPLES
+- **Real Testing**: Test actual functionality, not mocks
+- **Appropriate Tools**: Use browser for UI, curl for APIs, CLI for commands
+- **Complete Coverage**: Test all acceptance criteria
+- **Edge Cases**: Test boundary conditions and error scenarios
+- **Evidence**: Document validation results
+
+## 📋 MANDATORY VALIDATION STEPS
+
+### Step 1: Build and Compilation Check ✅
+
+**Requirements**:
+- TypeScript compiles without errors
+- Build process completes successfully
+- No type errors or warnings
+
+**Commands to Run**:
+```bash
+# Check TypeScript compilation
+npx tsc --noEmit --skipLibCheck
+
+# Run full build (includes validation)
+npm run build
+
+# Check for any 'as any' type bypassing
+grep -r "as any" src/ || echo "✅ No type bypassing found"
+```
+
+**What to Look For**:
+- Exit code 0 (success) for all commands
+- No error messages in output
+- Clean compilation without warnings
+
+### Step 2: Test Suite Validation 📊
+
+**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** (check .fraim/config.json for project-specific commands first):
+```bash
+# 1. FIRST: Read your project's validation commands from .fraim/config.json
+cat .fraim/config.json | grep -A 10 "validation"
+
+# 2. Run the comprehensive test suite (this runs ALL tests)
+npm test
+
+# 3. Also run smoke tests specifically to verify core functionality
+npm run test-smoke-ci
+
+# 4. Run all tests in CI mode for complete coverage
+npm run test-all-ci
+```
+
+**What to Look For**:
+- "All tests passed" or similar success message for ALL commands
+- No "FAILED" or "ERROR" in output from any test run
+- 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: Manual Functionality Testing 🧪
+
+**Requirements**:
+- Test actual user workflows end-to-end
+- Verify all acceptance criteria manually
+- Test both happy path and error scenarios
+
+**For UI Changes**:
+```bash
+# Start development server
+npm run dev
+# Then manually test in browser at http://localhost:3000
+```
+
+**For API Changes**:
+```bash
+# Test API endpoints
+curl -X GET http://localhost:3000/health
+curl -X POST http://localhost:3000/api/test -H "Content-Type: application/json" -d '{"test":"data"}'
+```
+
+**For CLI Changes**:
+```bash
+# Test CLI commands
+node bin/fraim.js --help
+node bin/fraim.js sync --dry-run
+```
+
+**What to Document**:
+- Specific steps you performed
+- What you clicked/typed/tested
+- Results you observed
+- Any errors encountered and how they were handled
+
+### Step 4: Git and Code Quality Check 🔍
+
+**Requirements**:
+- Git status is clean
+- No debugging code remains
+- Code follows quality standards
+
+**Commands to Run**:
+```bash
+# Check git status
+git status
+
+# 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 in core functionality
+grep -r "task-placeholder" src/ || echo "✅ No task placeholders found"
+
+# Validate registry paths (if applicable)
+npm run validate:registry
+```
+
+**What to Look For**:
+- Only intended files are modified
+- No console.log statements (except intentional logging)
+- No task placeholder comments in critical code
+- Clean working directory
+
+### Step 5: Bug-Specific Validation (For Bug Fixes) 🐛
+
+**Requirements**:
+- Original reproduction test now passes
+- Bug symptoms are gone
+- No regressions introduced
+
+**Commands to Run**:
+```bash
+# Run the specific repro test
+npm test -- path/to/repro/test.test.ts
+
+# Test the original bug scenario manually
+# (Follow the original reproduction steps)
+```
+
+**What to Verify**:
+- Repro test that was failing now passes
+- Original bug behavior is fixed
+- Related functionality still works
+
+### Step 6: Feature-Specific Validation (For Features) ✨
+
+**Requirements**:
+- New functionality works as specified
+- Integration with existing features works
+- All acceptance criteria met
+
+**What to Test**:
+- Main user scenarios from the spec
+- Edge cases and error conditions
+- Integration points with existing code
+- Performance (if applicable)
+
+## 🛠️ VALIDATION COMMANDS REFERENCE
+
+### Quick Health Check
+```bash
+# One-liner to check basic health
+npx tsc --noEmit --skipLibCheck && npm test && git status
+```
+
+### Comprehensive Validation
+```bash
+# Full validation suite
+npm run build && npm run test-all-ci && npm run validate:registry
+```
+
+### API Testing
+```bash
+# Test API health and basic functionality
+curl -f http://localhost:3000/health && echo "✅ API healthy"
+```
+
+### Build Verification
+```bash
+# Verify build artifacts are created correctly
+npm run build && ls -la dist/ && echo "✅ Build artifacts present"
+```
+
+## WORKFLOW
+
+### Step 1: Identify Validation Method
+
+**For UI Changes:**
+- Use browser to navigate and test
+- Verify visual correctness
+- Test user interactions
+- Check responsive behavior
+
+**For API Changes:**
+- Use curl or similar tools
+- Test all endpoints
+- Verify request/response formats
+- Test error handling
+
+**For Backend/CLI Changes:**
+- Run relevant commands
+- Test with various inputs
+- Verify output correctness
+- Test error conditions
+
+### Step 2: Test All Acceptance Criteria
+- Review acceptance criteria from implement-scoping phase
+- Test each criterion systematically
+- Document results for each
+- Verify all are met
+
+### Step 3: Test Edge Cases
+**Common edge cases:**
+- Empty inputs
+- Invalid inputs
+- Boundary values
+- Error conditions
+- Concurrent operations (if applicable)
+
+### Step 4: Document Results
+In evidence, include:
+- What was tested
+- How it was tested
+- Results of each test
+- Any issues found and fixed
+- Screenshots/output (if applicable)
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ All acceptance criteria tested and passing
+- ✅ Edge cases handled correctly
+- ✅ For bugs: repro test now passes
+- ✅ For features: new functionality works
+- ✅ No obvious bugs or issues
+- ✅ Validation results documented with evidence
+- ✅ All servers running without errors
+- ✅ 100% test success rate
+- ✅ Error scenarios tested and handled
+
+### Phase Incomplete If:
+- ❌ Acceptance criteria not met
+- ❌ For bugs: repro test still fails
+- ❌ For features: functionality doesn't work
+- ❌ Edge cases not handled
+- ❌ Obvious bugs found
+- ❌ Missing evidence for claims
+- ❌ Server errors present
+- ❌ Any tests failing
+
+### Report Back:
+When you complete this phase, call:
+
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "implement",
+  issueNumber: "{issue_number}",
+  currentPhase: "implement-validate", 
+  status: "complete",
+  findings: {
+    issueType: "bug" // or "feature" - Required for phase validation
+  },
+  evidence: {
+    buildPassed: "YES", // Did `npm run build` succeed?
+    testsPassed: "YES", // Did `npm test` show 100% pass rate?
+    manualValidationDone: "YES", // Did you manually test the functionality?
+    serversStarted: "YES", // Did servers start without errors?
+    reproTestPassed: "YES", // (For bugs) Does the repro test now pass?
+    featureWorking: "YES", // (For features) Does the new functionality work?
+    commandsRun: "npm run build && npm test", // What validation commands did you run?
+    summary: "All validation steps completed successfully. Build passes, all 15 tests pass, manual testing confirmed functionality works as expected."
+  }
+})
+```
+
+If validation reveals issues, report back with status "incomplete":
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "implement",
+  issueNumber: "{issue_number}",
+  currentPhase: "implement-validate", 
+  status: "incomplete",
+  findings: {
+    issueType: "bug" // or "feature" - Required for phase validation
+  },
+  evidence: {
+    buildPassed: "NO", // Specify what failed
+    testsPassed: "NO", // Be specific about failures
+    issues: ["Build failed with TypeScript errors", "3 tests failing", "Manual testing revealed login button not working"],
+    commandsRun: "npm run build && npm test",
+    nextAction: "Need to return to implement phase to fix these issues"
+  }
+})
+```
+
+## SCRIPTS
+
+**Browser testing:**
+```bash
+npm run dev  # Start dev server
+# Then manually test in browser
+```
+
+**API testing:**
+```bash
+curl -X POST http://localhost:3000/api/endpoint -d '{"data": "value"}'
+```
+
+**CLI testing:**
+```bash
+npm run cli -- command --flag value
+```
+
+**Run all tests:**
+```bash
+npm test
+```

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

@@ -0,0 +1,304 @@
+# Phase: Quality Review
+
+## INTENT
+To perform final quality checks ensuring all design aspects are implemented, code quality standards are met, and the work is production-ready.
+
+## OUTCOME
+Confirmation that:
+- All design aspects implemented
+- Code compiles without errors
+- All tests pass
+- Code quality standards met
+- No debugging code remains
+- Git status is clean
+
+## RULES FOR THIS PHASE
+
+### Success Criteria
+Read `registry/rules/agent-success-criteria.md` via `get_fraim_file` for the complete framework. This phase tests ALL criteria:
+- **Integrity** (truthful reporting of all validation results)
+- **Correctness** (code compiles, tests pass, follows architecture)
+- **Completeness** (all requirements implemented, all validation steps completed)
+- **Independence** (thorough self-validation without asking user)
+- **Speed** (efficient validation process)
+
+### Simplicity Principles
+Read `registry/rules/simplicity.md` via `get_fraim_file` for complete guidelines. Key for quality review:
+- **Focus on the assigned issue only** - ensure no unrelated changes
+- **Manual Validation Required** - verify implementation works as expected
+- **Resource Waste Prevention** - efficient validation process
+
+### Architecture Compliance
+Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then use `get_fraim_file` to read the full architecture guidelines. Verify all architectural standards are met.
+
+### Git Operations (if needed)
+When using git commands directly (if MCP tools unavailable), read `registry/rules/git-safe-commands.md` via `get_fraim_file` to avoid interactive commands that hang agents.
+
+## PRINCIPLES
+- **Comprehensive**: Check all quality dimensions
+- **Standards Compliance**: Follow all coding standards
+- **Production Ready**: Code is ready for deployment
+- **Clean State**: No temporary code or artifacts
+
+## WORKFLOW
+
+### Step 1: TypeScript Compilation Check
+```bash
+npx tsc --noEmit --skipLibCheck
+```
+
+**Must exit with code 0** (no errors)
+
+If compilation fails:
+- Review errors carefully
+- Fix type issues
+- Re-compile to verify
+- Return to implement phase if major issues found
+
+### Step 2: Build Verification
+```bash
+npm run build
+```
+
+**Must complete successfully:**
+- No build errors
+- All validation steps pass
+- Build artifacts created
+
+If build fails:
+- Check build output for specific errors
+- Fix issues found
+- Re-run build to verify
+
+### Step 3: Complete Test Suite
+```bash
+npm test
+```
+
+**All tests must pass:**
+- No failures (0 failed tests)
+- No timeouts
+- No skipped tests (unless intentional)
+
+**Additional test commands:**
+```bash
+# Run smoke tests
+npm run test-smoke-ci
+
+# Run all tests in CI mode
+npm run test-all-ci
+```
+
+If tests fail:
+- Review failure output
+- Fix failing tests
+- Return to appropriate phase if needed
+
+### Step 4: Code Quality Verification
+
+**Check for type bypassing:**
+```bash
+grep -r "as any" src/ || echo "✅ No type bypassing found"
+```
+**Must find zero instances** (or only justified ones with comments)
+
+**Check for debugging code:**
+```bash
+grep -r "console.log" src/ | grep -v "// OK" | grep -v "logger" || echo "✅ No debug logs found"
+```
+**Should find zero or only intentional logging**
+
+**Check for TODO comments:**
+```bash
+grep -r "TODO" src/ || echo "✅ No TODOs found"
+```
+**Core functionality should have no TODOs**
+
+**Validate registry paths:**
+```bash
+npm run validate:registry
+```
+**Must pass without errors**
+
+### Step 5: Git Status Verification
+```bash
+git status
+```
+
+**Should show:**
+- Only intended changes
+- No untracked files (except evidence docs)
+- No accidentally modified files
+- Clean working directory
+
+**Check recent commits:**
+```bash
+git log --oneline -5
+```
+**Verify commits are meaningful and related to the issue**
+
+### Step 6: Design Completeness Check (Features)
+
+For features, verify all design aspects implemented:
+
+**API Contracts:**
+```bash
+# Test all API endpoints mentioned in spec
+curl -X GET http://localhost:3000/api/endpoint1
+curl -X POST http://localhost:3000/api/endpoint2 -d '{"test":"data"}'
+```
+
+**Data Models:**
+- Check database schemas match design
+- Verify data validation rules
+- Test data persistence
+
+**User Interfaces:**
+- All UI components from design implemented
+- Responsive behavior works
+- Error states handled
+
+**Integration Points:**
+- External API integrations work
+- Internal service communication works
+- Authentication/authorization implemented
+
+### Step 7: Bug Fix Verification (Bugs)
+
+For bugs, verify:
+
+**Minimal Changes:**
+```bash
+git diff HEAD~1 --stat
+```
+**Should show focused, minimal changes**
+
+**Root Cause Addressed:**
+- Review the fix against original bug report
+- Ensure fix addresses cause, not just symptoms
+- Verify no new issues introduced
+
+**Regression Testing:**
+```bash
+# Run tests related to the bug area
+npm test -- --grep "related-functionality"
+```
+
+### Step 8: Comprehensive Health Check
+
+**One-liner health check:**
+```bash
+npx tsc --noEmit --skipLibCheck && npm test && git status
+```
+
+**Full validation suite:**
+```bash
+npm run build && npm run test-all-ci && npm run validate:registry
+```
+
+**API health check (if applicable):**
+```bash
+curl -f http://localhost:3000/health && echo "✅ API healthy"
+```
+
+### Step 9: Mandatory Pre-Completion Reflection
+
+**🚨 CRITICAL - Minimum 10 minutes required**
+
+Read and complete reflection from `rules/mandatory-pre-completion-reflection.md` via `get_fraim_file`:
+
+**Phase 1: Claim Verification (3 min)**
+- What am I claiming works?
+- What evidence do I have?
+- Have I actually tested these claims?
+- Are ALL tests passing (100%)?
+- Have I investigated every error in the logs?
+
+**Phase 2: Risk Analysis (3 min)**
+- What could go wrong?
+- What didn't I test?
+- What edge cases might exist?
+- What would a user experience if they tried this?
+
+**Phase 3: Validation Plan Check (2 min)**
+- Do I cover all spec scenarios?
+- Are there gaps in my testing?
+- Did I validate manually?
+- Would I ship this to customers right now?
+- Would I bet money this works end-to-end?
+
+**Phase 4: Self-Audit (2 min)**
+- Did I follow all rules?
+- Would I bet money this works?
+- Am I being honest about status?
+- Am I rushing to claim completion?
+
+**Document reflection analysis and address any blockers identified.**
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ TypeScript compiles (exit code 0)
+- ✅ All tests pass
+- ✅ No "as any" type bypassing
+- ✅ No debugging code remains
+- ✅ Git status clean
+- ✅ (Features) All design aspects implemented
+- ✅ (Bugs) Changes minimal and focused
+- ✅ (If applicable) Design feedback addressed
+- ✅ Test integrity verified (no modified test criteria)
+- ✅ Mandatory reflection completed
+- ✅ All reflection blockers addressed
+
+### Phase Incomplete If:
+- ❌ TypeScript compilation errors
+- ❌ Any tests fail
+- ❌ Code quality issues found
+- ❌ Design aspects incomplete
+- ❌ Unintended changes in git
+- ❌ Design feedback not addressed
+- ❌ Test criteria were modified without approval
+- ❌ Reflection not completed
+- ❌ Reflection identified unaddressed blockers
+
+**Full quality check:**
+```bash
+npx tsc --noEmit --skipLibCheck && npm test && grep -r "as any" src/ && git status
+```
+
+### Report Back:
+When you complete this phase, call:
+
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "implement",
+  issueNumber: "{issue_number}",
+  currentPhase: "quality-review", 
+  status: "complete",
+  evidence: {
+    typescriptCompiles: "YES", // Did `npx tsc --noEmit --skipLibCheck` succeed?
+    buildSucceeds: "YES", // Did `npm run build` succeed?
+    allTestsPass: "YES", // Did `npm test` show 100% pass rate?
+    noTypeBypass: "YES", // Did `grep -r "as any" src/` find zero instances?
+    noDebugCode: "YES", // Did you remove console.log statements?
+    gitStatusClean: "YES", // Does `git status` show only intended changes?
+    designComplete: "YES", // (Features) All design aspects implemented?
+    changesMinimal: "YES", // (Bugs) Changes are focused and minimal?
+    reflectionDone: "YES", // Did you complete the mandatory reflection?
+    commandsRun: "npx tsc --noEmit --skipLibCheck && npm run build && npm test && git status",
+    summary: "All quality checks passed. TypeScript compiles clean, all tests pass, git status clean, reflection completed."
+  },
+  iterationCount: 1
+})
+```
+
+## QUALITY STANDARDS
+Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then use `get_fraim_file` to read the full quality standards. Key requirements include:
+- No 'as any' type bypassing
+- Proper error handling
+- Consistent code style
+- Meaningful variable names
+- Appropriate code comments
+- Tests follow architecture standards
+- Tests validate real functionality
+- No tests that default to passing