fraim-framework 2.0.43 → 2.0.45

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

@@ -0,0 +1,286 @@
+# Phase: Code
+
+## INTENT
+To write the minimal, testable code needed to fix the bug or implement the feature, following approved designs and established patterns.
+
+## OUTCOME
+Working implementation that:
+- Fixes the bug or implements the feature
+- Follows approved design/RFC
+- Includes comprehensive tests
+- Maintains code quality
+- Is ready for validation
+
+## 🎯 SUCCESS MINDSET
+
+**Your Goal**: Working application that users can actually use, not just passing tests.
+
+**Critical Success Factors**:
+- 🔍 **Manual validation is MANDATORY** - You WILL test in browser/API/CLI manually
+- ⚠️ **Every error must be investigated** - No assumptions, no "that's probably fine"
+- 🚫 **No placeholder code** - Implement complete solutions, no task placeholders or "for now" comments
+- 📊 **100% test success required** - 91% is failure, 99% is failure, only 100% is success
+- 🏗️ **Prototype-first** - Build simplest end-to-end solution, then engineer it properly
+
+## RULES FOR THIS PHASE
+
+### Success Criteria
+Read `registry/rules/agent-success-criteria.md` via `get_fraim_file` for the complete framework. Focus especially on:
+- **Integrity** (never claim tests pass if you didn't run them)
+- **Correctness** (follow architecture, tests must pass, no `any` types)
+- **Completeness** (implement everything in the issue description)
+
+### Simplicity Principles
+Read `registry/rules/simplicity.md` via `get_fraim_file` for complete guidelines. Critical for coding phase:
+- **Prototype-First Development**: Build simplest solution that works end-to-end, validate manually, then engineer correctly
+- **Manual Validation Required**: Test with browser/curl before creating automated tests
+- **Resource Waste Prevention**: Maximum 2 retries for expensive operations
+- **NEVER use placeholder comments** like "For now", "task placeholders", "fix-me notes"
+
+### 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. Follow all architectural standards - no shortcuts.
+
+### Git Operations (if needed)
+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 implementation fails**: Return to implement-scoping phase to re-understand requirements
+- **If tests fail**: Fix implementation until all tests pass
+- **If architecture violations**: Return to implement-scoping to understand constraints better
+
+## PRINCIPLES
+- **Design-Driven**: Follow approved RFCs and design documents
+- **Minimal Implementation**: Write only code needed for this issue
+- **Test-First**: Write tests before or alongside implementation
+- **Quality Focus**: Maintain code quality and follow patterns
+- **Complete**: All aspects of design/spec implemented
+
+## 📋 ENHANCED WORKFLOW
+
+### Step 1: Prototype-First Development
+
+**Build Simplest End-to-End Solution**:
+- Focus on getting something working, not perfect
+- Don't worry about code quality initially
+- Prove the approach works before optimizing
+- Get basic functionality working first
+
+**Manual Validation (CRITICAL)**:
+- Test every step manually using browser/curl/CLI
+- Verify each acceptance criteria works
+- Take screenshots/capture output as evidence
+- Fix any issues found immediately
+
+### Step 2: Review Design/Spec
+
+**For Bugs:**
+- Review bug description and repro test
+- Understand root cause
+- Plan minimal fix
+
+**For Features:**
+- Review approved RFC/design document
+- Review spike/POC findings (if applicable)
+- Understand all acceptance criteria
+- Plan implementation approach
+
+### Step 3: Check for Design and PR Feedback
+
+**CRITICAL**: Before implementing, check for feedback:
+- **Design Review Feedback**: `docs/evidence/{issue_number}-design-reviewer-feedback.md`
+- **Feature Review Feedback**: `docs/evidence/{issue_number}-feature-reviewer-feedback.md`
+- **PR Review Feedback**: `docs/evidence/{issue_number}-implement-feedback.md`
+
+**If any feedback exists:**
+- **MUST address all UNADDRESSED items** before proceeding
+- Update feedback files after addressing each item
+- Change status from UNADDRESSED to ADDRESSED with resolution details
+- Cannot skip or defer feedback items
+- Phase cannot complete until all feedback is addressed
+
+**PR Feedback File Format** (if exists):
+```markdown
+### Comment X - ADDRESSED
+- **Author**: reviewer_name
+- **Comment**: Original feedback
+- **Status**: ADDRESSED
+- **Resolution**: How you addressed this feedback
+```
+
+### Step 4: Implement Changes
+
+**For Bugs:**
+- Make minimal changes to fix the issue
+- Focus on root cause, not symptoms
+- Avoid unrelated changes
+- Keep diff small and focused
+
+**For Features:**
+- Implement all aspects from design/spec
+- Follow existing patterns and architecture
+- Create necessary files/modules
+- Implement all API contracts
+- Implement all data models
+- Implement all user interfaces
+- No placeholder code for core functionality
+
+### Step 5: Fix All Errors (MANDATORY)
+
+**Error Investigation Requirements**:
+- **Every error in logs must be investigated**
+- **No error is "expected" until proven**
+- **Fix root causes, not symptoms**
+- **Document why any remaining errors are acceptable**
+
+**Common Error Sources**:
+- Server startup errors
+- API connection errors
+- Database connection errors
+- TypeScript compilation errors
+- Test execution errors
+
+### Step 6: Write Comprehensive Tests
+
+**MANDATORY**: Every issue requires tests - no exceptions.
+
+**For Bugs:**
+- Verify repro test from implement-repro phase now passes
+- Add additional edge case tests if needed
+- Ensure tests cover the fix
+
+**For Features:**
+- Write tests for all acceptance criteria
+- Test main user scenarios
+- Test edge cases
+- Test error conditions
+- Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then read the local architecture document to understand the full test architecture standards
+
+**Test Requirements:**
+- Use shared-server-utils.ts for server tests
+- Unique API keys per test
+- Proper cleanup in finally blocks
+- No individual server instances
+- Proper timeouts (5-10s for network calls)
+- Tests must validate real functionality, not mocks
+- No tests that default to passing
+
+**Test Tagging Guidelines:**
+Tag tests appropriately to ensure proper test suite execution:
+
+- **`smoke`**: Tag tests as "smoke" if they verify:
+  - Core system functionality (CLI commands, server startup, basic workflows)
+  - Critical user journeys (init, sync, basic operations)
+  - Integration points between major components
+  - Functionality that, if broken, would make the system unusable
+
+- **`integration`**: Tests that verify multiple components working together
+- **`unit`**: Tests that verify individual functions or classes in isolation
+- **`e2e`**: End-to-end tests that verify complete user workflows
+
+**Smoke Test Execution Rules:**
+If ANY tests are tagged "smoke" or you're modifying core functionality:
+1. **MANDATORY**: Run full smoke test suite: `npm run test-smoke-ci`
+2. **MANDATORY**: Include smoke test output in evidence
+3. **MANDATORY**: All smoke tests must pass before proceeding
+4. **BLOCKING**: Smoke test failures block phase completion
+
+### Step 7: Basic Compilation Check
+
+**Verify code compiles:**
+```bash
+npx tsc --noEmit --skipLibCheck
+```
+
+**Must exit with code 0** (no errors)
+
+If compilation fails:
+- Fix TypeScript errors
+- Re-compile
+- Iterate until clean
+
+**Note**: Full validation, testing, and manual verification will be handled in subsequent phases (implement-validate, implement-smoke, implement-regression).
+
+## 📸 EVIDENCE REQUIREMENTS
+
+You MUST provide concrete evidence for all claims:
+
+1. **Implementation Complete**: Code written per design/spec
+2. **Tests Written**: Comprehensive test coverage for new functionality
+3. **Compilation Success**: TypeScript compiles without errors
+4. **Basic Functionality**: Code implements the required features/fixes
+
+**Note**: Screenshots, manual validation, server logs, and API responses will be captured in the implement-validate phase.
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ Implementation complete per design/spec
+- ✅ (Bugs) Minimal, focused changes
+- ✅ (Features) All design aspects implemented
+- ✅ Tests written for new functionality
+- ✅ TypeScript compiles cleanly
+- ✅ Design feedback addressed (if applicable)
+- ✅ **PR feedback addressed** (if `docs/evidence/{issue_number}-implement-feedback.md` exists)
+- ✅ Code implements required features/fixes
+
+### Phase Incomplete If:
+- ❌ Design/spec not fully implemented
+- ❌ No tests written for new functionality
+- ❌ TypeScript compilation errors
+- ❌ Design feedback not addressed
+- ❌ **PR feedback not addressed** (UNADDRESSED items remain in feedback file)
+- ❌ Code doesn't implement required functionality
+
+### Report Back:
+When you complete this phase, call:
+
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "implement",
+  issueNumber: "{issue_number}",
+  currentPhase: "implement-code", 
+  status: "complete",
+  findings: {
+    issueType: "bug", // or "feature" - Required for phase validation
+    evidence: "Brief summary of what you implemented and validated"
+  },
+  evidence: {
+    implementation: "Brief summary of what you implemented",
+    testsWritten: "Description of tests created for new functionality",
+    compilationStatus: "TypeScript compiles without errors",
+    feedbackAddressed: "All design/PR feedback addressed (if applicable)"
+  }
+})
+```
+
+If implementation incomplete, iterate:
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "implement",
+  issueNumber: "{issue_number}",
+  currentPhase: "implement-code",
+  status: "incomplete", 
+  findings: {
+    issueType: "bug", // or "feature" - Required for phase validation
+    uncertainties: ["Issues encountered", "What needs to be fixed"]
+  }
+})
+```
+```
+
+## SCRIPTS
+
+**Run tests:**
+```bash
+npm test -- path/to/test.test.ts
+```
+
+**Compile TypeScript:**
+```bash
+npx tsc --noEmit --skipLibCheck
+```
+
+**Start dev server (for manual testing in validate phase):**
+```bash
+npm run dev
+```

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

@@ -0,0 +1,120 @@
+# Phase: Implement-Completeness-Review
+
+## INTENT
+To verify that all design aspects have been implemented and that the work fully addresses the requirements from the design document or issue specification.
+
+## OUTCOME
+Confirmation that:
+- All design aspects implemented
+- All acceptance criteria met
+- Implementation matches design specifications
+- Work is complete and ready for finalization
+
+## PRINCIPLES
+- **Design Fidelity**: Implementation must match design specifications
+- **Complete Coverage**: All design aspects must be addressed
+- **Evidence-Based**: Use existing comprehensive review workflows
+
+## WORKFLOW
+
+### Step 1: Check for PR Feedback to Address
+
+- Check for PR feedback file: `docs/evidence/{issue_number}-implement-feedback.md`
+- If feedback file exists, verify all comments have been addressed before proceeding
+
+**PR Feedback Validation:**
+- Read the feedback file to see all previous review rounds
+- Ensure all items marked as UNADDRESSED have been resolved
+- Update feedback file with ADDRESSED status and resolution details
+- Cannot proceed until all feedback items are properly addressed
+
+**Expected behavior:**
+- All UNADDRESSED items in feedback file must be resolved
+- Each resolved item should have detailed resolution explanation
+- Phase cannot complete with any remaining UNADDRESSED items
+
+### Step 2: Execute Design Review Workflow
+
+Use the comprehensive design validation workflow:
+- Read `registry/workflows/reviewer/review-implementation-vs-design-spec.md` via `get_fraim_file`
+- Follow the complete systematic review process
+- This workflow provides detailed checklists, validation steps, and templates
+- Works for both bugs and features - all should be reviewed against their design spec
+
+### Step 3: Execute Review Workflow
+
+**Follow the design review workflow completely:**
+- Use all the checklists provided
+- Execute all validation steps
+- Create feedback documents using the templates
+- Follow the iteration limits (max 3)
+
+### Step 4: 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. Verify implementation follows all design standards.
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ PR comments addressed (if applicable)
+- ✅ PR comment verification script passes (if applicable)
+- ✅ Appropriate review workflow executed completely
+- ✅ All workflow checklists completed
+- ✅ All design aspects verified per workflow
+- ✅ Evidence quality meets workflow standards
+- ✅ Feedback documents created using workflow templates
+- ✅ Architecture compliance verified
+
+### Phase Incomplete If:
+- ❌ PR comments not properly addressed
+- ❌ PR comment verification script fails
+- ❌ Review workflow not followed completely
+- ❌ Workflow checklists incomplete
+- ❌ Design aspects not verified per workflow standards
+- ❌ Evidence quality insufficient per workflow criteria
+- ❌ Feedback documents missing or not using templates
+
+### Report Back:
+When you complete this phase, call:
+
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "implement",
+  issueNumber: "{issue_number}",
+  currentPhase: "implement-completeness-review", 
+  status: "complete",
+  findings: {
+    issueType: "bug" // or "feature" - Required for phase validation
+  },
+  evidence: {
+    reviewWorkflowUsed: "review-implementation-vs-design-spec", // Which workflow was used
+    workflowChecklistsComplete: "YES", // All checklists from workflow completed?
+    designAspectsVerified: "YES", // All design aspects verified per workflow?
+    evidenceQualityMet: "YES", // Evidence meets workflow standards?
+    feedbackDocumentsCreated: "YES", // Feedback documents created using templates?
+    architectureCompliant: "YES", // Architecture compliance verified?
+    reviewDecision: "APPROVE", // APPROVE/REQUEST_CHANGES/REJECT per workflow
+    summary: "Completed systematic design review using comprehensive workflow. All design aspects verified and documented."
+  }
+})
+```
+
+If review reveals issues:
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "implement",
+  issueNumber: "{issue_number}",
+  currentPhase: "implement-completeness-review", 
+  status: "incomplete",
+  findings: {
+    issueType: "bug" // or "feature" - Required for phase validation
+  },
+  evidence: {
+    reviewWorkflowUsed: "review-implementation-vs-design-spec",
+    reviewDecision: "REQUEST_CHANGES", // or "REJECT"
+    issuesFound: ["Missing test case X per workflow checklist", "Design requirement Y not implemented"],
+    feedbackDocumentLocation: "docs/evidence/{issue}-design-reviewer-feedback.md",
+    nextAction: "Implementation agent must address feedback per workflow iteration process"
+  }
+})
+```

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

@@ -0,0 +1,173 @@
+# 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

@@ -0,0 +1,104 @@
+# 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"
+  }
+})
+```