fraim-framework 2.0.44 → 2.0.45

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

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

package/dist/registry/ai-manager-rules/shared-phases/finalize.md

@@ -0,0 +1,169 @@
+# Phase: Finalize
+
+## INTENT
+To prepare completed work for human review by setting proper labels, creating/updating PR, and documenting evidence.
+
+## OUTCOME
+Work is ready for human review with:
+- Proper issue labels applied
+- PR created/updated with work
+- Evidence documented
+- Clean handoff to next phase or review
+
+## PRINCIPLES
+- **Complete Documentation**: Evidence shows all work done
+- **Proper Labels**: Issue status reflects readiness
+- **Clear Communication**: PR and evidence are clear
+- **Ready for Review**: No blockers for human reviewer
+
+## 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 documentation of all work completed)
+- **Completeness** (all finalization steps completed)
+
+### Simplicity Principles
+Read `registry/rules/simplicity.md` via `get_fraim_file` for complete guidelines. Key for finalization:
+- **Focus on the assigned issue only** - document only relevant work
+- **Clear communication** - evidence should be easy to understand
+
+### 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.
+
+## WORKFLOW
+
+### Step 1: Update Issue Labels
+
+**Remove:**
+- `status:wip`
+- Any phase-specific labels (e.g., `phase:spec`, `phase:design`, `phase:impl`)
+
+**Add:**
+- `status:needs-review`
+
+**GitHub Repository Context:**
+Read `.fraim/config.json` for:
+- `git.repoOwner` - GitHub repository owner
+- `git.repoName` - GitHub repository name
+
+Use GitHub MCP tools to update labels.
+
+### Step 2: Create Evidence Document
+
+**File location:**
+```
+docs/evidence/{issue_number}-{workflow_type}-evidence.md
+```
+
+**Evidence document should include:**
+
+#### Summary
+- Issue number and title
+- Workflow type (spec, design, implement, test)
+- Brief description of work completed
+
+#### Work Completed
+**For Spec Workflow:**
+- Specification document created
+- High-fidelity HTML mocks (if UI changes)
+- Requirements coverage
+
+**For Design Workflow:**
+- Technical design document
+- Architecture decisions
+- API specifications
+- Database schema (if applicable)
+
+**For Implement Workflow:**
+- Implementation details
+- Key files changed
+- Approach taken
+- Testing completed
+
+**For Test Workflow:**
+- Test suite created/enhanced
+- Coverage metrics
+- Test results
+
+#### Validation
+- How work was validated
+- Validation results
+- Screenshots/output (if applicable)
+
+#### Quality Checks
+- All deliverables complete
+- Documentation clear and professional
+- Work ready for next phase or review
+
+#### Phase Completion
+- All phases completed for this workflow
+- Evidence from each phase
+- Any iterations or challenges
+
+### Step 3: Verify PR Exists
+
+**Verify PR:**
+- PR exists for the feature branch
+- PR title reflects the issue and workflow
+- PR description includes context and links to deliverables
+
+**If PR doesn't exist:**
+- Create PR manually
+- Link to issue
+- Add evidence document link
+
+### Step 4: Add PR Comment
+
+Add comment to PR with link to evidence:
+```
+{Workflow_type} workflow complete. Evidence document: docs/evidence/{issue_number}-{workflow_type}-evidence.md
+
+All phases completed:
+{workflow_specific_phases_checklist}
+
+Ready for human review.
+```
+
+### Step 5: Final Verification
+
+**Checklist:**
+- ✅ Issue labels updated
+- ✅ Evidence document created and complete
+- ✅ PR exists and is ready
+- ✅ PR comment added with evidence link
+- ✅ All deliverables complete
+- ✅ Git status clean
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ Issue has `status:needs-review` label
+- ✅ Issue does not have workflow phase labels
+- ✅ Evidence document exists and is complete
+- ✅ PR exists and is ready for review
+- ✅ PR has comment linking to evidence
+- ✅ All previous phases complete
+
+### Phase Incomplete If:
+- ❌ Labels not updated
+- ❌ Evidence document missing or incomplete
+- ❌ PR not ready
+- ❌ Previous phases not complete
+
+### Report Back:
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "{workflow_type}",
+  issueNumber: "{issue_number}",
+  currentPhase: "finalize", 
+  status: "complete",
+  evidence: {
+    labelsUpdated: "Issue has status:needs-review label",
+    evidenceDocument: "docs/evidence/{issue_number}-{workflow_type}-evidence.md created",
+    prStatus: "PR ready for review",
+    prComment: "PR comment added with evidence link",
+    allPhasesComplete: "All {workflow_type} phases completed successfully"
+  }
+})
+```

package/dist/registry/ai-manager-rules/shared-phases/submit-pr.md

@@ -0,0 +1,202 @@
+# Phase: submit-pr
+
+## INTENT
+To submit completed work for review by creating/updating PR, setting proper labels, and documenting evidence.
+
+## OUTCOME
+Work is submitted for review with:
+- PR created/updated with work
+- Proper issue labels applied
+- Evidence documented
+- Ready to enter PR review phase
+
+## PRINCIPLES
+- **Complete Documentation**: Evidence shows all work done
+- **Proper Labels**: Issue status reflects PR submission
+- **Clear Communication**: PR and evidence are clear
+- **Ready for Review**: No blockers for PR review process
+
+## 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 documentation of all work completed)
+- **Completeness** (all finalization steps completed)
+
+### Simplicity Principles
+Read `registry/rules/simplicity.md` via `get_fraim_file` for complete guidelines. Key for finalization:
+- **Focus on the assigned issue only** - document only relevant work
+- **Clear communication** - evidence should be easy to understand
+
+### 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.
+
+## WORKFLOW
+
+### Step 1: Create Evidence Document
+
+**File location:**
+```
+docs/evidence/{issue_number}-{workflow_type}-evidence.md
+```
+
+**Evidence document should include:**
+
+#### Summary
+- Issue number and title
+- Workflow type (spec, design, implement, test)
+- Brief description of work completed
+
+#### Work Completed
+**For Spec Workflow:**
+- Specification document created
+- High-fidelity HTML mocks (if UI changes)
+- Requirements coverage
+
+**For Design Workflow:**
+- Technical design document
+- Architecture decisions
+- API specifications
+- Database schema (if applicable)
+
+**For Implement Workflow:**
+- Implementation details
+- Key files changed
+- Approach taken
+- Testing completed
+
+**For Test Workflow:**
+- Test suite created/enhanced
+- Coverage metrics
+- Test results
+
+#### PR Feedback History (if applicable)
+**CRITICAL**: If PR feedback file exists (`docs/evidence/{issue_number}-{workflow_type}-feedback.md`), include its complete contents in the evidence document under this section.
+
+This shows reviewers:
+- All previous feedback received
+- How each item was addressed
+- Complete audit trail of review iterations
+
+#### Validation
+- How work was validated
+- Validation results
+- Screenshots/output (if applicable)
+
+#### Quality Checks
+- All deliverables complete
+- Documentation clear and professional
+- Work ready for next phase or review
+
+#### Phase Completion
+- All phases completed for this workflow
+- Evidence from each phase
+- Any iterations or challenges
+
+### Step 2: Commit and Sync Work
+
+**Commit all changes:**
+- Stage all modified files
+- Create commit with descriptive message
+- Push to feature branch
+
+**Commit message format:**
+```
+{workflow_type}({issue_number}): complete {phase_name} phase
+
+- Evidence document created
+- All deliverables complete
+- Ready for review
+```
+
+### Step 3: Verify PR Exists
+
+**Verify PR:**
+- PR exists for the feature branch
+- PR title reflects the issue and workflow
+- PR description includes context and links to deliverables
+
+**If PR doesn't exist:**
+- Create PR manually
+- Link to issue
+- Add evidence document link
+
+### Step 4: Add PR Comment
+
+Add comment to PR with link to evidence:
+```
+{Workflow_type} workflow complete. Evidence document: docs/evidence/{issue_number}-{workflow_type}-evidence.md
+
+All phases completed:
+{workflow_specific_phases_checklist}
+
+**PR Feedback History**: 
+{If feedback file exists, include: "This submission addresses all feedback from previous review rounds. See evidence document for complete feedback history and resolutions."}
+
+Ready for human review.
+```
+
+### Step 5: Update Issue Labels
+
+**Remove:**
+- `status:wip`
+
+**Add:**
+- `status:needs-review`
+
+**Keep:**
+- Current phase label (e.g., `phase:spec`, `phase:design`, `phase:impl`) to indicate which phase is in PR
+
+**GitHub Repository Context:**
+Read `.fraim/config.json` for:
+- `git.repoOwner` - GitHub repository owner
+- `git.repoName` - GitHub repository name
+
+Use GitHub MCP tools to update labels.
+
+### Step 6: Final Verification
+
+**Checklist:**
+- ✅ Issue labels updated (kept phase label, added needs-review)
+- ✅ Evidence document created and complete
+- ✅ All work committed and pushed to feature branch
+- ✅ PR exists and is ready
+- ✅ PR comment added with evidence link
+- ✅ All deliverables complete
+- ✅ Git status clean
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ Issue has `status:needs-review` label
+- ✅ Issue keeps current phase label to indicate what needs review
+- ✅ Evidence document exists and is complete
+- ✅ All work committed and synced to remote
+- ✅ PR exists and is ready for review
+- ✅ PR has comment linking to evidence
+- ✅ All previous phases complete
+
+### Phase Incomplete If:
+- ❌ Labels not updated correctly
+- ❌ Evidence document missing or incomplete
+- ❌ Work not committed and synced
+- ❌ PR not ready
+- ❌ Previous phases not complete
+
+### Report Back:
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "{workflow_type}",
+  issueNumber: "{issue_number}",
+  currentPhase: "submit-pr", 
+  status: "complete",
+  evidence: {
+    labelsUpdated: "Issue has status:needs-review and keeps phase label",
+    evidenceDocument: "docs/evidence/{issue_number}-{workflow_type}-evidence.md created",
+    workCommitted: "All changes committed and pushed to feature branch",
+    prStatus: "PR ready for review",
+    prComment: "PR comment added with evidence link",
+    allPhasesComplete: "All {workflow_type} phases completed successfully"
+  }
+})
+```