fraim-framework 2.0.44 → 2.0.46

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.

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

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

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