fraim-framework 2.0.66 → 2.0.67

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

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

@@ -0,0 +1,159 @@
+# 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 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
+
+## 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 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 use `get_fraim_file` to read 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 (Bugs):
+- ✅ Repro test now PASSES
+- ✅ Bug confirmed fixed
+- ✅ Test output documented
+
+### Phase Complete When (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 use `get_fraim_file` to read the full test architecture guidelines
+- Follow test requirements from the implement workflow (use `get_fraim_file({ path: "workflows/product-building/implement.md" })`)
+- 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`
+
+## 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: "regression", 
+  status: "complete",
+  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: "regression", 
+  status: "complete",
+  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/repro.md

@@ -0,0 +1,101 @@
+# Phase: Repro (Bug Fixes Only)
+
+## 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 use `get_fraim_file` to read 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: "repro", 
+  status: "complete",
+  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/scoping.md

@@ -0,0 +1,93 @@
+# Phase: 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 use `get_fraim_file` to read the full architecture guidelines. Understanding the architecture helps with proper scoping.
+
+## WORKFLOW
+
+### Step 1: Read Issue Description
+- 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: "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.