fraim-framework 2.0.52 → 2.0.55

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

@@ -1,225 +0,0 @@
-# Phase: 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.
-
-## 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
-
-## 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 1: Build 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
-```
-
-**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 tests pass (100% success rate)
-- No timeouts or hanging tests
-- Reasonable test count
-
-**Commands to Run**:
-```bash
-# Run all tests
-npm test
-
-# Run smoke tests specifically
-npm run test-smoke-ci
-
-# Run all tests in CI mode
-npm run test-all-ci
-```
-
-**What to Look For**:
-- "All tests passed" or similar success message
-- No "FAILED" or "ERROR" in output
-- No timeout messages
-- Reasonable execution time
-
-### 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 TODO 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 TODO comments
-grep -r "TODO" src/ || echo "✅ No TODOs found"
-```
-
-**What to Look For**:
-- Zero instances of "as any" (or only justified ones with comments)
-- No console.log statements (except intentional logging)
-- No TODO comments in critical code
-
-### Step 5: Registry Validation (If Applicable) ✅
-
-**Commands to Run**:
-```bash
-# Validate registry paths
-npm run validate:registry
-```
-
-**What to Look For**:
-- No validation errors
-- All registry paths valid
-
-## 🛠️ TECHNICAL COMMANDS REFERENCE
-
-### Quick Health Check
-```bash
-# One-liner to check basic health
-npx tsc --noEmit --skipLibCheck && npm test && git status
-```
-
-### Comprehensive Technical Check
-```bash
-# Full technical validation suite
-npm run build && npm run test-all-ci && git status
-```
-
-### Build Verification
-```bash
-# Verify build artifacts are created correctly
-npm run build && ls -la dist/ && echo "✅ Build artifacts present"
-```
-
-## VALIDATION
-
-### Phase Complete When:
-- ✅ TypeScript compiles (exit code 0)
-- ✅ 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 TODO comments in core functionality
-- ✅ Registry validation passes (if applicable)
-- ✅ All technical checks documented
-
-### Phase Incomplete If:
-- ❌ TypeScript compilation errors
-- ❌ Build fails
-- ❌ ANY test fails
-- ❌ Git status shows unintended changes
-- ❌ Code quality issues found
-- ❌ Registry validation fails
-
-**If ANY check fails, return to implement phase immediately.**
-
-## RULES FOR THIS PHASE
-
-### Technical Standards
-- Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then use `get_fraim_file` to read the full technical standards
-- Use Successful Debugging Patterns from `rules/successful-debugging-patterns.md` via `get_fraim_file`
-- When using git commands directly (if MCP tools unavailable), read `registry/rules/git-safe-commands.md` via `get_fraim_file`
-
-## SCRIPTS
-
-**Run all technical checks:**
-```bash
-npm run build && npm test && git status
-```
-
-**Run smoke tests specifically:**
-```bash
-npm run test-smoke-ci
-```
-
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "smoke", 
-  status: "complete",
-  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: "smoke", 
-  status: "incomplete",
-  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"
-  }
-})
-```

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

@@ -1,118 +0,0 @@
-# Phase: Spike (Features Only)
-
-## INTENT
-To build a proof-of-concept that validates the technical approach, tests uncertain or risky aspects, and confirms the design is viable before full implementation.
-
-## OUTCOME
-A working POC that:
-- Validates key technical assumptions
-- Tests risky or uncertain aspects
-- Gets user approval
-- Informs any necessary design updates
-
-## PRINCIPLES
-- **Spike-First Development**: Follow the spike-first rule for unfamiliar technology
-- **Risk Reduction**: Focus on highest-risk or most uncertain aspects
-- **Quick Validation**: Build minimal POC, not production code
-- **User Approval**: Get explicit approval before proceeding
-- **Design Updates**: Update design doc with findings
-
-## WORKFLOW
-
-### Step 1: Review Design Document
-- Read the technical design/RFC thoroughly
-- Identify technical assumptions
-- Note any unfamiliar technologies or patterns
-- List risky or uncertain aspects
-
-### Step 2: Identify Spike Scope
-**Focus on:**
-- Unfamiliar technology or libraries
-- Integration points with external systems
-- Performance-critical components
-- Complex algorithms or logic
-- Uncertain technical feasibility
-
-**Do NOT spike:**
-- Well-understood patterns
-- Standard CRUD operations
-- Simple UI changes
-- Routine implementations
-
-### Step 3: Build Proof-of-Concept
-- Create minimal code to test assumptions
-- Focus on proving/disproving technical approach
-- Don't worry about production quality
-- Document what you're testing
-
-### Step 4: Test Key Assumptions
-- Run the POC
-- Verify it works as expected
-- Test edge cases if relevant
-- Document findings
-
-### Step 5: Get User Approval
-- Present POC to user
-- Explain what was validated
-- Share any findings or concerns
-- **Wait for explicit approval** before proceeding
-
-### Step 6: Update Design Document
-If POC revealed:
-- Better approaches
-- Technical constraints
-- Performance considerations
-- Integration challenges
-
-**Update the design document** with findings
-
-## VALIDATION
-
-### Phase Complete When:
-- ✅ POC built and tested
-- ✅ Key technical assumptions validated
-- ✅ User has approved the approach
-- ✅ Design document updated (if needed)
-- ✅ Ready to proceed with full implementation
-
-### Phase Incomplete If:
-- ❌ POC doesn't work as expected
-- ❌ Technical approach not viable
-- ❌ User hasn't approved
-- ❌ Significant findings not documented
-
-## RULES FOR THIS PHASE
-
-### Spike-First Development
-Read `registry/rules/spike-first-development.md` via `get_fraim_file` for complete spike methodology.
-
-### Architecture Compliance
-Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then use `get_fraim_file` to read the full architecture guidelines.
-
-### 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.
-
-## SCRIPTS
-Run POC:
-```bash
-npm run spike  # or appropriate command
-node spike/your-poc.js
-```
-
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "spike", 
-  status: "complete",
-  evidence: {
-    pocLocation: "spike/auth-flow.ts",
-    validationResults: "OAuth2 integration works as expected",
-    userApproval: "User approved approach on [date]",
-    designUpdates: "Updated design doc with token refresh findings"
-  }
-})
-```

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

@@ -1,347 +0,0 @@
-# Phase: 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 use `get_fraim_file` to read 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 `registry/rules/git-safe-commands.md` via `get_fraim_file` to avoid interactive commands that hang agents.
-
-## 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 tests pass (100% success rate)
-- No timeouts or hanging tests
-- Meaningful test coverage
-
-**Commands to Run**:
-```bash
-# Run all tests
-npm test
-
-# Run smoke tests specifically
-npm run test-smoke-ci
-
-# Run all tests in CI mode
-npm run test-all-ci
-```
-
-**What to Look For**:
-- "All tests passed" or similar success message
-- No "FAILED" or "ERROR" in output
-- Reasonable test count (not just 1-2 tests)
-- No timeout messages
-
-### 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 TODO comments in core functionality
-grep -r "TODO" src/ || echo "✅ No TODOs 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 TODO 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 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: "validate", 
-  status: "complete",
-  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: "validate", 
-  status: "incomplete",
-  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
-```