fraim-framework 2.0.52 → 2.0.55

package/dist/registry/ai-manager-rules/implement.json

@@ -1,153 +0,0 @@
-{
-  "workflowType": "implement",
-  "description": "Implementation phase validation ensures that code changes are complete, properly tested with high-quality tests, and ready for production deployment. This phase enforces rigorous testing standards and design completeness.",
-  "validationRules": [
-    {
-      "step": 1,
-      "description": "Verify issue is labeled with phase:implement",
-      "passCriteria": "Issue has 'phase:implement' label applied",
-      "weight": "blocking",
-      "category": "process"
-    },
-    {
-      "step": 2,
-      "description": "Verify all aspects of design are complete",
-      "passCriteria": "All design requirements from spec/RFC are implemented: API contracts, data models, user interfaces, error handling patterns, and integration points. No placeholder code or TODO comments remain for core functionality.",
-      "weight": "blocking",
-      "category": "design-completeness"
-    },
-    {
-      "step": 3,
-      "description": "Verify all test cases from design document are written",
-      "passCriteria": "Every test case specified in the design document/RFC validation plan has a corresponding automated test. Test coverage includes all user scenarios, edge cases, and error conditions outlined in the design.",
-      "weight": "blocking",
-      "category": "test-completeness"
-    },
-    {
-      "step": 4,
-      "description": "Verify all test cases follow architecture standards",
-      "passCriteria": "Tests follow the Shared Server Architecture pattern from docs/architecture/architecture.md: 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).",
-      "weight": "blocking",
-      "category": "test-architecture"
-    },
-    {
-      "step": 5,
-      "description": "Verify all test cases have been run and are passing",
-      "passCriteria": "All tests pass successfully. Test output shows 0 failures, 0 timeouts, and all assertions succeed. Tests complete within reasonable time limits (<60s total, <10s per test).",
-      "weight": "blocking",
-      "category": "test-execution"
-    },
-    {
-      "step": 6,
-      "description": "Verify tests do not mock the objects they should be testing",
-      "passCriteria": "Tests validate real functionality, not mocked behavior. Core business logic is tested against actual implementations. Mocks are only used for external dependencies (databases, APIs, file system) not for the code under test.",
-      "weight": "blocking",
-      "category": "test-quality"
-    },
-    {
-      "step": 7,
-      "description": "Verify tests do not default to passing when unable to test",
-      "passCriteria": "No tests contain 'return true' without validation, empty test bodies, or assertions that always pass. Every test performs meaningful validation of expected behavior and will fail if the code is broken.",
-      "weight": "blocking",
-      "category": "test-quality"
-    },
-    {
-      "step": 8,
-      "description": "Verify tests use flow testing instead of static analysis",
-      "passCriteria": "Tests execute actual code paths and validate runtime behavior. Tests call functions, trigger workflows, and verify outcomes. Static analysis (type checking, linting) supplements but does not replace functional testing.",
-      "weight": "blocking",
-      "category": "test-quality"
-    },
-    {
-      "step": 9,
-      "description": "Check TypeScript compilation passes",
-      "command": "npx tsc --noEmit --skipLibCheck",
-      "passCriteria": "TypeScript compilation completes without errors",
-      "weight": "blocking",
-      "category": "code-quality"
-    },
-    {
-      "step": 10,
-      "description": "Check code quality standards",
-      "passCriteria": "No 'as any' type bypassing, proper error handling, consistent code style, meaningful variable names, and appropriate code comments",
-      "weight": "blocking",
-      "category": "code-quality"
-    },
-    {
-      "step": 11,
-      "description": "Verify implementation matches design exactly",
-      "passCriteria": "Implementation follows the technical design/RFC precisely and addresses all specified requirements. API signatures, data structures, and behavior match the design specification.",
-      "weight": "blocking",
-      "category": "design-compliance"
-    },
-    {
-      "step": 12,
-      "description": "Check comprehensive error handling and edge cases",
-      "passCriteria": "Proper error handling implemented for all failure scenarios, edge cases covered with tests, graceful degradation where appropriate, and meaningful error messages",
-      "weight": "blocking",
-      "category": "robustness"
-    },
-    {
-      "step": 13,
-      "description": "Validate API contracts and interfaces",
-      "passCriteria": "All API contracts match specification, proper input validation, consistent response formats, and backward compatibility maintained",
-      "weight": "blocking",
-      "category": "api-compliance"
-    },
-    {
-      "step": 14,
-      "description": "Check security best practices",
-      "passCriteria": "Input sanitization, proper authentication/authorization, no security vulnerabilities, secure handling of sensitive data",
-      "weight": "blocking",
-      "category": "security"
-    },
-    {
-      "step": 15,
-      "description": "Check documentation is updated",
-      "passCriteria": "Code comments, README updates, API documentation, and inline documentation reflect all changes",
-      "weight": "warning",
-      "category": "documentation"
-    },
-    {
-      "step": 16,
-      "description": "Verify performance considerations",
-      "passCriteria": "No obvious performance regressions, efficient algorithms used, proper resource management, and performance tests where applicable",
-      "weight": "warning",
-      "category": "performance"
-    },
-    {
-      "step": 17,
-      "description": "Validate evidence document exists",
-      "command": "find \"docs/evidence\" -name \"*{issue_number}*implementation*\" -type f",
-      "passCriteria": "Implementation evidence document exists with test results, validation details, and proof of all requirements being met",
-      "weight": "warning",
-      "category": "documentation"
-    }
-  ],
-  "gradingCriteria": {
-    "passRequirements": [
-      "ALL blocking validation steps must pass",
-      "At least 80% of warning validation steps should pass",
-      "All design aspects are fully implemented",
-      "All test cases from design document are written and passing",
-      "Tests follow architecture standards and test real functionality",
-      "No tests mock objects under test or default to passing",
-      "Tests use flow testing to validate runtime behavior",
-      "Code is production-ready and maintainable"
-    ],
-    "failRequirements": [
-      "ANY blocking validation step fails",
-      "Design implementation is incomplete",
-      "Test cases from design document are missing",
-      "Tests violate architecture standards",
-      "Tests mock the objects they should be testing",
-      "Tests default to passing without proper validation",
-      "Tests rely on static analysis instead of flow testing",
-      "Code has obvious bugs or security issues"
-    ]
-  },
-  "reportingFormat": {
-    "requiredFields": ["pass", "reasons"],
-    "instructions": "Evaluate each validation step rigorously. Pay special attention to test quality - verify that tests actually test the intended functionality and follow architecture standards. If ANY blocking step fails, you must report pass=false. Focus on design completeness, test quality, and production readiness."
-  }
-}

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

@@ -1,169 +0,0 @@
-# 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/spec-phases/finalize.md

@@ -1,60 +0,0 @@
-# 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
-
-## WORKFLOW
-
-### Step 1: Apply Issue Labels
-- Remove current phase label (e.g., `phase:spec`, `phase:design`, `phase:impl`)
-- Add `status:needs-review` label
-- Keep any other relevant labels
-
-### Step 2: Create/Update Pull Request
-- Ensure PR exists for the feature branch
-- Update PR title to reflect completed work
-- Update PR description with summary of work completed
-- Link to relevant documents (specs, designs, evidence)
-
-### Step 3: Document Evidence
-- Create evidence file at `docs/evidence/{issue_number}-{workflow}-evidence.md`
-- Document key decisions made
-- List deliverables created
-- Note any recommendations for next phase
-
-### Step 4: Prepare Handoff
-- Ensure all work is committed to git
-- Verify documentation is complete
-- Confirm work is ready for human review
-
-## VALIDATION
-
-### Phase Complete When:
-- ✅ Issue labels updated (`status:needs-review`)
-- ✅ PR created/updated with work summary
-- ✅ Evidence documented
-- ✅ All work committed to git
-- ✅ Ready for human review
-
-### Report Back:
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "{workflow_type}",
-  issueNumber: "{issue_number}",
-  currentPhase: "finalize", 
-  status: "complete",
-  evidence: {
-    labelsApplied: ["status:needs-review"],
-    prUpdated: true,
-    evidenceDocumented: "docs/evidence/{issue_number}-{workflow}-evidence.md",
-    workCommitted: true
-  }
-})
-```

package/dist/registry/ai-manager-rules/spec-phases/spec.md

@@ -1,102 +0,0 @@
-# Phase: Spec
-
-## INTENT
-To create a comprehensive feature specification that clearly defines customer needs, desired outcomes, user experience, and validation criteria.
-
-## OUTCOME
-A complete specification document that:
-- Identifies the target customer and their needs
-- Defines the desired outcome and success criteria
-- Describes the user experience in detail
-- Includes high-fidelity mocks for UI changes
-- Provides a comprehensive validation plan
-- Analyzes alternatives and competitive landscape
-
-## PRINCIPLES
-- **Customer-First**: Start with customer identification and needs
-- **Outcome-Driven**: Focus on what the customer wants to achieve
-- **Experience-Detailed**: Provide step-by-step user workflows
-- **Validation-Ready**: Include specific, executable validation steps
-- **Template-Compliant**: Follow FEATURESPEC template structure
-
-## WORKFLOW
-
-### Step 1: Load Template and Rules
-- Call `get_fraim_file({ path: "templates/specs/FEATURESPEC-TEMPLATE.md" })`
-- Call `get_fraim_file({ path: "rules/communication.md" })`
-- Call `get_fraim_file({ path: "rules/pr-workflow-completeness.md" })`
-
-### Step 2: Create Specification Document
-- Create spec file at `docs/feature specs/{issue_number}-{kebab-case-title}.md`
-- Follow FEATURESPEC template structure exactly
-- Include all required sections:
-  - Customer identification
-  - Customer's desired outcome
-  - Customer problem definition
-  - User experience with detailed workflows
-  - Validation plan
-  - Alternatives analysis
-  - Competitive landscape
-
-### Step 3: Create High-Fidelity Mocks (if UI changes)
-If the feature involves UI changes:
-- Create HTML/CSS mocks in `docs/feature specs/mocks/`
-- Name files: `{issue_number}-{descriptive-name}.html`
-- Include at least 3 different views/states
-- Link mocks in the specification document
-- **Note**: Markdown code blocks are NOT sufficient - must be actual HTML files
-
-### Step 4: Validate Completeness
-- Ensure all template sections are complete
-- Verify customer focus is clear and specific
-- Check that user experience includes step-by-step workflows
-- Confirm validation plan is actionable and executable
-- Review alternatives and competitive analysis
-
-### Step 5: Apply Labels
-- Label the GitHub issue with `phase:spec`
-- This will trigger automatic PR creation/update
-
-## VALIDATION
-
-### Phase Complete When:
-- ✅ Specification document created using FEATURESPEC template
-- ✅ All required sections completed with substantial content
-- ✅ Customer and desired outcome clearly identified
-- ✅ User experience includes detailed step-by-step workflows
-- ✅ High-fidelity mocks created (if UI changes required)
-- ✅ Validation plan includes specific, executable steps
-- ✅ Alternatives and competitive landscape analyzed
-- ✅ Issue labeled with `phase:spec`
-
-### Phase Incomplete If:
-- ❌ Specification document missing or incomplete
-- ❌ Template structure not followed
-- ❌ Customer identification vague or missing
-- ❌ User experience lacks detailed workflows
-- ❌ UI changes specified but no HTML mocks provided
-- ❌ Validation plan not actionable
-- ❌ Alternatives or competitive analysis missing
-
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "spec",
-  issueNumber: "{issue_number}",
-  currentPhase: "spec", 
-  status: "complete",
-  evidence: {
-    specDocument: "docs/feature specs/{issue_number}-{title}.md",
-    templateUsed: "FEATURESPEC-TEMPLATE.md",
-    mockFiles: ["docs/feature specs/mocks/{issue_number}-view1.html", "..."],
-    namingConvention: "{issue_number}-{kebab-case-title}.md",
-    issueLabeled: "phase:spec"
-  },
-  findings: {
-    completedSections: ["Customer identification", "Customer desired outcome", "..."],
-    keyInsights: ["Key insight 1", "Key insight 2", "..."]
-  }
-})
-```

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

@@ -1,118 +0,0 @@
-# Phase: Validate (Spec)
-
-## INTENT
-To systematically validate that the specification is complete, follows template structure, and meets all quality criteria before proceeding to the next workflow phase.
-
-## OUTCOME
-Confirmation that:
-- Specification follows FEATURESPEC template structure
-- All required sections are complete and substantial
-- Customer focus is clear and specific
-- User experience includes detailed workflows
-- High-fidelity mocks are provided (if UI changes)
-- Validation plan is actionable
-- Quality standards are met consistently
-
-## PRINCIPLES
-- **Template Compliance**: Strict adherence to FEATURESPEC structure
-- **Completeness**: All sections must be substantial, not placeholder text
-- **Customer Focus**: Clear identification of who and what
-- **Actionable Validation**: Validation plan must be executable
-- **Quality Standards**: Professional-grade specification ready for design phase
-
-## WORKFLOW
-
-### Step 1: Load Validation Rules
-- Call `get_fraim_file({ path: "ai-manager-rules/spec.json" })`
-- Review all validation criteria and grading requirements
-
-### Step 2: Execute Validation Checklist
-
-**Blocking Validation Steps (ALL must pass):**
-
-1. **Issue Labeling**: Verify issue has `phase:spec` label
-2. **Document Location**: Confirm spec exists at `docs/feature specs/{issue_number}-*.md` with >1000 characters
-3. **Template Structure**: Check all required sections present:
-   - Customer identification
-   - Customer's desired outcome  
-   - Customer problem definition
-   - User experience
-   - Validation plan
-   - Alternatives analysis
-   - Competitive landscape
-4. **Customer Section**: Customer clearly identified with specific details
-5. **Desired Outcome**: Outcome is clear, measurable, describes end goal
-6. **Problem Definition**: Specific explanation of why current state insufficient
-7. **User Experience**: Step-by-step workflow (start in X, click Y, see Z)
-8. **High-Fidelity Mocks**: If UI changes, HTML/CSS files in mocks folder (not markdown)
-9. **Validation Plan**: Specific, executable steps (browser tests, API calls, scenarios)
-10. **Requirements Coverage**: All original issue requirements addressed
-
-**Warning Validation Steps (80% should pass):**
-
-11. **Alternatives Analysis**: Table with alternatives and reasons for rejection
-12. **Competitive Landscape**: Table with competitors, solutions, market research
-
-### Step 3: Quality Assessment
-- Check for placeholder text or incomplete sections
-- Verify professional writing quality
-- Ensure consistency throughout document
-- Confirm all links and references work
-
-### Step 4: Generate Validation Report
-Document findings for each validation step:
-- Pass/Fail for each blocking step
-- Pass/Fail for each warning step  
-- Specific reasons for any failures
-- Overall assessment and recommendations
-
-## VALIDATION
-
-### Phase Complete When:
-- ✅ ALL blocking validation steps pass
-- ✅ At least 80% of warning validation steps pass
-- ✅ No placeholder text or incomplete sections
-- ✅ Quality standards met consistently
-- ✅ Validation report generated with evidence
-
-### Phase Incomplete If:
-- ❌ ANY blocking validation step fails
-- ❌ Multiple warning validation steps fail
-- ❌ Placeholder text or incomplete sections found
-- ❌ Quality issues identified
-- ❌ Requirements not properly addressed
-
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "spec",
-  issueNumber: "{issue_number}",
-  currentPhase: "validate", 
-  status: "complete",
-  evidence: {
-    validationReport: "All 10 blocking steps passed, 2/2 warning steps passed",
-    blockingStepsPassed: 10,
-    warningStepsPassed: 2,
-    totalWarningSteps: 2,
-    qualityAssessment: "Professional grade, ready for design phase",
-    validationDecision: "PASS"
-  }
-})
-```
-
-If validation fails:
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "spec",
-  issueNumber: "{issue_number}",
-  currentPhase: "validate", 
-  status: "incomplete",
-  findings: {
-    failedSteps: ["Step 8: High-fidelity mocks missing", "Step 9: Validation plan not actionable"],
-    validationDecision: "FAIL",
-    nextAction: "Return to spec phase to address failed validation steps"
-  }
-})
-```