fraim-framework 2.0.26 → 2.0.30

package/registry/scripts/verify-pr-comments.sh

@@ -1,70 +1,70 @@
-#!/bin/bash
-# verify-pr-comments.sh
-# Ensures agents properly retrieve and address PR comments
-
-set -e
-
-PR_NUMBER=$1
-
-# Load repository config from .fraim/config.json
-CONFIG_FILE=".fraim/config.json"
-if [ ! -f "$CONFIG_FILE" ]; then
-    echo "Error: Config file not found at $CONFIG_FILE" >&2
-    exit 1
-fi
-
-if ! command -v node &> /dev/null; then
-    echo "Error: node is required but not installed." >&2
-    exit 1
-fi
-
-# Extract values using node reading from stdin
-NODE_SCRIPT="
-const fs = require('fs');
-try {
-    const input = fs.readFileSync(0, 'utf-8');
-    const config = JSON.parse(input);
-    const repo = config.git;
-    if (!repo || !repo.repoOwner || !repo.repoName) {
-        process.exit(1);
-    }
-    console.log(\`\${repo.repoOwner}:\${repo.repoName}\`);
-} catch (e) {
-    process.exit(1);
-}
-"
-
-REPO_INFO=$(cat "$CONFIG_FILE" | node -e "$NODE_SCRIPT")
-if [ $? -ne 0 ]; then
-    echo "Error: Failed to parse repository config from $CONFIG_FILE" >&2
-    echo "Required: git.repoOwner, git.repoName" >&2
-    exit 1
-fi
-
-IFS=':' read -r REPO_OWNER REPO_NAME <<< "$REPO_INFO"
-
-if [ -z "$PR_NUMBER" ]; then
-    echo "❌ ERROR: PR number required"
-    echo "Usage: $0 <PR_NUMBER>"
-    exit 1
-fi
-
-echo "🔍 Verifying PR comment processing for #$PR_NUMBER ($REPO_OWNER/$REPO_NAME)"
-
-# Get all comments
-gh api "repos/$REPO_OWNER/$REPO_NAME/pulls/$PR_NUMBER/comments?per_page=100" \
-  --jq '.[] | "[\(.id)] \(.path // "pr"):\(.line // "general") - \(.body)"' \
-  > pr-comments-verification.txt
-
-COMMENT_COUNT=$(wc -l < pr-comments-verification.txt)
-echo "📋 Found $COMMENT_COUNT comments"
-echo "📄 Comments saved to pr-comments-verification.txt"
-
-if [ "$COMMENT_COUNT" -eq 0 ]; then
-    echo "✅ No comments found - agent can proceed"
-    exit 0
-fi
-
-echo ""
-echo "⚠️  Agent MUST address each comment before claiming completion"
-echo "📝 Agent must provide evidence table showing resolution of all $COMMENT_COUNT comments"
+#!/bin/bash
+# verify-pr-comments.sh
+# Ensures agents properly retrieve and address PR comments
+
+set -e
+
+PR_NUMBER=$1
+
+# Load repository config from config.json
+CONFIG_FILE=".fraim/config.json"
+if [ ! -f "$CONFIG_FILE" ]; then
+    echo "Error: Config file not found at $CONFIG_FILE" >&2
+    exit 1
+fi
+
+if ! command -v node &> /dev/null; then
+    echo "Error: node is required but not installed." >&2
+    exit 1
+fi
+
+# Extract values using node reading from stdin
+NODE_SCRIPT="
+const fs = require('fs');
+try {
+    const input = fs.readFileSync(0, 'utf-8');
+    const config = JSON.parse(input);
+    const repo = config.git;
+    if (!repo || !repo.repoOwner || !repo.repoName) {
+        process.exit(1);
+    }
+    console.log(\`\${repo.repoOwner}:\${repo.repoName}\`);
+} catch (e) {
+    process.exit(1);
+}
+"
+
+REPO_INFO=$(cat "$CONFIG_FILE" | node -e "$NODE_SCRIPT")
+if [ $? -ne 0 ]; then
+    echo "Error: Failed to parse repository config from $CONFIG_FILE" >&2
+    echo "Required: git.repoOwner, git.repoName" >&2
+    exit 1
+fi
+
+IFS=':' read -r REPO_OWNER REPO_NAME <<< "$REPO_INFO"
+
+if [ -z "$PR_NUMBER" ]; then
+    echo "❌ ERROR: PR number required"
+    echo "Usage: $0 <PR_NUMBER>"
+    exit 1
+fi
+
+echo "🔍 Verifying PR comment processing for #$PR_NUMBER ($REPO_OWNER/$REPO_NAME)"
+
+# Get all comments
+gh api "repos/$REPO_OWNER/$REPO_NAME/pulls/$PR_NUMBER/comments?per_page=100" \
+  --jq '.[] | "[\(.id)] \(.path // "pr"):\(.line // "general") - \(.body)"' \
+  > pr-comments-verification.txt
+
+COMMENT_COUNT=$(wc -l < pr-comments-verification.txt)
+echo "📋 Found $COMMENT_COUNT comments"
+echo "📄 Comments saved to pr-comments-verification.txt"
+
+if [ "$COMMENT_COUNT" -eq 0 ]; then
+    echo "✅ No comments found - agent can proceed"
+    exit 0
+fi
+
+echo ""
+echo "⚠️  Agent MUST address each comment before claiming completion"
+echo "📝 Agent must provide evidence table showing resolution of all $COMMENT_COUNT comments"

package/registry/scripts/verify-test-coverage.ts

@@ -5,7 +5,7 @@
  * Verifies test coverage against validation plans and outputs data to the console.
  * Used by the verify-test-coverage bootstrapping workflow.
  * 
- * Usage: npx tsx registry/scripts/verify-test-coverage.ts
+ * Usage: npx tsx <this-script>
  */
 
 import * as path from 'path';

package/registry/templates/bootstrap/ARCHITECTURE-TEMPLATE.md

@@ -1,53 +1,53 @@
-# Architecture Documentation: <project-name>
-
-## 1. Overview
-<Briefly describe the purpose and goals of the project.>
-
-## 2. Tech Stack Choices
-
-| Category | Choice | Rationale |
-| :--- | :--- | :--- |
-| **Language** | <e.g. TypeScript> | <e.g. Type safety and developer productivity> |
-| **Runtime** | <e.g. Node.js> | <e.g. Ubiquity and ecosystem> |
-| **Frameworks** | <e.g. Express, Fastify, React> | <e.g. Robustness and community support> |
-| **Database** | <e.g. MongoDB, PostgreSQL> | <e.g. Data structure requirements> |
-| **Testing** | <e.g. Vitest, Playwright> | <e.g. Modern toolchain and speed> |
-
-## 3. Architectural Layers
-
-Describe the layers of the system and their responsibilities.
-
-### 3.1. [Layer Name, e.g., API/Interface Layer]
-- **Responsibility**: <e.g., Handling HTTP requests, validation, and CLI entry points.>
-- **Key Modules**: <e.g., `src/server.ts`, `src/cli/`>
-
-### 3.2. [Layer Name, e.g., Application/Business Logic Layer]
-- **Responsibility**: <e.g., Core business rules and orchestrating domain services.>
-- **Key Modules**: <e.g., `src/services/`, `src/orchestrator/`>
-
-### 3.3. [Layer Name, e.g., Data/Infrastructure Layer]
-- **Responsibility**: <e.g., Persistence, external API integrations, and low-level utilities.>
-- **Key Modules**: <e.g., `src/db/`, `src/clients/`>
-
-## 4. Key Components & Modules
-
-<mermaid>
-graph TD
-    A[Component A] --> B[Component B]
-    B --> C[External API]
-    B --> D[Database]
-</mermaid>
-
-### 4.1 [Component Name]
-<Description of the component's role and internal structure.>
-
-## 5. Data Flow
-<Describe how information moves through the system from an input (e.g., user request) to output/persistence.>
-
-## 6. Design Patterns & Principles
-- **Pattern 1**: <e.g., Dependency Injection for testability.>
-- **Pattern 2**: <e.g., Event-driven architecture for async processing.>
-
-## 7. Configuration & Environment
-- **FRAIM Config**: Located at `.fraim/config.json`.
-- **Environment Variables**: <List critical variables here.>
+# Architecture Documentation: <project-name>
+
+## 1. Overview
+<Briefly describe the purpose and goals of the project.>
+
+## 2. Tech Stack Choices
+
+| Category | Choice | Rationale |
+| :--- | :--- | :--- |
+| **Language** | <e.g. TypeScript> | <e.g. Type safety and developer productivity> |
+| **Runtime** | <e.g. Node.js> | <e.g. Ubiquity and ecosystem> |
+| **Frameworks** | <e.g. Express, Fastify, React> | <e.g. Robustness and community support> |
+| **Database** | <e.g. MongoDB, PostgreSQL> | <e.g. Data structure requirements> |
+| **Testing** | <e.g. Vitest, Playwright> | <e.g. Modern toolchain and speed> |
+
+## 3. Architectural Layers
+
+Describe the layers of the system and their responsibilities.
+
+### 3.1. [Layer Name, e.g., API/Interface Layer]
+- **Responsibility**: <e.g., Handling HTTP requests, validation, and CLI entry points.>
+- **Key Modules**: <e.g., `src/server.ts`, `src/cli/`>
+
+### 3.2. [Layer Name, e.g., Application/Business Logic Layer]
+- **Responsibility**: <e.g., Core business rules and orchestrating domain services.>
+- **Key Modules**: <e.g., `src/services/`, `src/orchestrator/`>
+
+### 3.3. [Layer Name, e.g., Data/Infrastructure Layer]
+- **Responsibility**: <e.g., Persistence, external API integrations, and low-level utilities.>
+- **Key Modules**: <e.g., `src/db/`, `src/clients/`>
+
+## 4. Key Components & Modules
+
+<mermaid>
+graph TD
+    A[Component A] --> B[Component B]
+    B --> C[External API]
+    B --> D[Database]
+</mermaid>
+
+### 4.1 [Component Name]
+<Description of the component's role and internal structure.>
+
+## 5. Data Flow
+<Describe how information moves through the system from an input (e.g., user request) to output/persistence.>
+
+## 6. Design Patterns & Principles
+- **Pattern 1**: <e.g., Dependency Injection for testability.>
+- **Pattern 2**: <e.g., Event-driven architecture for async processing.>
+
+## 7. Configuration & Environment
+- **FRAIM Config**: Located at `config.json`.
+- **Environment Variables**: <List critical variables here.>

package/registry/templates/evidence/Implementation-BugEvidence.md

@@ -1,86 +1,86 @@
-# Bug: <Title>
-Issue: #<issue>  
-Bug Spec: <Link to Bug Spec>
-PR: <Link to PR>
-
-## Completeness Evidence
- - Issue tagged with label `phase:impl`: Yes/No
- - Issue tagged with label `status:needs-review`: Yes/No
- - All files committed/synced to branch: Yes/No
- - Table with following columns 
-   - PR Comment
-   - How Addressed
-
-## Implementation Quality Checkpoints
- - [ ] Code complexity reviewed (no overengineering)
- - [ ] No resource waste (excessive retries, delays, workarounds)
- - [ ] Solution based on proven approach from design phase
- - [ ] All new files/functions are actually used
-
-## Validation Evidence
-- Complete valiation performed as suggested in bug spec: Yes/No
-- **MANDATORY**: Evidence must reflect actual validation status, not assumptions
-- **MANDATORY**: Cannot mark automated validations as "pending" without attempting them first
-- Table with following columns
-   - Validation Step (manual vs automated)
-   - Validation Result (pass vs fail)
-   - Evidence (actual command/output or explanation why not applicable)
-   - Failure Analysis (if fail)
-
-## New Files/Functions Created
- - Table with the following columns
-    - File/Function Name
-    - Purpose
-    - Who is using/importing/calling it
-    - Is it actually used? (Yes/No - if No, explain why it exists)
-
-## New Tests Added
-- Required if existing test cases did not repro the bug, Optional if bug fix made previously failing test cases pass
-- **MANDATORY**: For each new test case added, you MUST:
-  - Show actual test execution command run
-  - Show actual test output (exit code and results)
-  - Document whether it passed/failed
-  - Cannot claim tests "need fixes" without attempting execution first
-
-## Test Execution Log
-**MANDATORY**: Include actual test execution results below:
-
-```bash
-# Example: Running test file
-$ npm run test -- test-XXX-fix.ts
-# [Include actual output here]
-# Exit code: 0 (success) or non-zero (failure)
-```
-
-**For each test file**:
-- Command executed: `[command]`
-- Exit code: `[0 or non-zero]`
-- Passed tests: `[count]`
-- Failed tests: `[count]`
-- Output excerpt: `[relevant lines]`
-
-## Existing Test Suites Run
- - Table with following columns
-    - Test Suite
-    - Was it Run (if not, why not - it's ok to not run a suite if there is no impact of your work to it as covered in agent-testing-guidelines.md)
-    - Failing Tests
-    - Failure Analysis (if any tests fail)
-
-## Pre-Completion Reflection
-
-[Include reflection analysis here following `.ai-agents/rules/mandatory-pre-completion-reflection.md`]
-
-✅ Reflection Phase 1 (Claim Verification) completed: YES/NO
-✅ Reflection Phase 2 (Risk Analysis) completed: YES/NO
-✅ Reflection Phase 3 (Validation Plan Check) completed: YES/NO
-✅ Reflection Phase 4 (Self-Audit) completed: YES/NO
-✅ All blockers from reflection addressed: YES/NO
-✅ Confidence level: X% (must be ≥ 90% to proceed)
-
-**Reflection Summary:**
-[Brief summary of key findings from reflection]
-
-## Continous Learning
- - Table with following columns
-    - Learning
+# Bug: <Title>
+Issue: #<issue>  
+Bug Spec: <Link to Bug Spec>
+PR: <Link to PR>
+
+## Completeness Evidence
+ - Issue tagged with label `phase:impl`: Yes/No
+ - Issue tagged with label `status:needs-review`: Yes/No
+ - All files committed/synced to branch: Yes/No
+ - Table with following columns 
+   - PR Comment
+   - How Addressed
+
+## Implementation Quality Checkpoints
+ - [ ] Code complexity reviewed (no overengineering)
+ - [ ] No resource waste (excessive retries, delays, workarounds)
+ - [ ] Solution based on proven approach from design phase
+ - [ ] All new files/functions are actually used
+
+## Validation Evidence
+- Complete valiation performed as suggested in bug spec: Yes/No
+- **MANDATORY**: Evidence must reflect actual validation status, not assumptions
+- **MANDATORY**: Cannot mark automated validations as "pending" without attempting them first
+- Table with following columns
+   - Validation Step (manual vs automated)
+   - Validation Result (pass vs fail)
+   - Evidence (actual command/output or explanation why not applicable)
+   - Failure Analysis (if fail)
+
+## New Files/Functions Created
+ - Table with the following columns
+    - File/Function Name
+    - Purpose
+    - Who is using/importing/calling it
+    - Is it actually used? (Yes/No - if No, explain why it exists)
+
+## New Tests Added
+- Required if existing test cases did not repro the bug, Optional if bug fix made previously failing test cases pass
+- **MANDATORY**: For each new test case added, you MUST:
+  - Show actual test execution command run
+  - Show actual test output (exit code and results)
+  - Document whether it passed/failed
+  - Cannot claim tests "need fixes" without attempting execution first
+
+## Test Execution Log
+**MANDATORY**: Include actual test execution results below:
+
+```bash
+# Example: Running test file
+$ npm run test -- test-XXX-fix.ts
+# [Include actual output here]
+# Exit code: 0 (success) or non-zero (failure)
+```
+
+**For each test file**:
+- Command executed: `[command]`
+- Exit code: `[0 or non-zero]`
+- Passed tests: `[count]`
+- Failed tests: `[count]`
+- Output excerpt: `[relevant lines]`
+
+## Existing Test Suites Run
+ - Table with following columns
+    - Test Suite
+    - Was it Run (if not, why not - it's ok to not run a suite if there is no impact of your work to it as covered in agent-testing-guidelines.md)
+    - Failing Tests
+    - Failure Analysis (if any tests fail)
+
+## Pre-Completion Reflection
+
+[Include reflection analysis here following `get_fraim_file({ path: "rules/mandatory-pre-completion-reflection.md" })`]
+
+✅ Reflection Phase 1 (Claim Verification) completed: YES/NO
+✅ Reflection Phase 2 (Risk Analysis) completed: YES/NO
+✅ Reflection Phase 3 (Validation Plan Check) completed: YES/NO
+✅ Reflection Phase 4 (Self-Audit) completed: YES/NO
+✅ All blockers from reflection addressed: YES/NO
+✅ Confidence level: X% (must be ≥ 90% to proceed)
+
+**Reflection Summary:**
+[Brief summary of key findings from reflection]
+
+## Continous Learning
+ - Table with following columns
+    - Learning
     - Agent Rule Updates (what agent rule file was updated to ensure the learning is durable)

package/registry/templates/evidence/Implementation-FeatureEvidence.md

@@ -1,121 +1,121 @@
-# Feature: <Title>
-Issue: #<issue>  
-Tech Spec: <Link to tech spec>
-PR: <Link to PR>
-
-## Completeness Evidence
- - All phases of tech spec complete: Yes/No 
- - Issue tagged with label `phase:impl`: Yes/No
- - Issue tagged with label `status:needs-review`: Yes/No
- - All files committed/synced to branch: Yes/No
- - Table with following columns 
-   - PR Comment
-   - How Addressed
-
-## Implementation Quality Checkpoints
- - [ ] Code complexity reviewed (no overengineering)
- - [ ] No resource waste (excessive retries, delays, workarounds)
- - [ ] Solution based on proven prototype from design phase
- - [ ] All new files/functions are actually used
-
-## Validation Evidence
- - Complete validation performed as suggested in tech spec: Yes/No
- - **IMPORTANT**: Post full test output (not just "tests passing ✅")
- - Table with following columns
-    - Validation Step (manual vs automated)
-    - Validation Result (pass vs fail)
-    - Failure Analysis (if fail)
-
-### Example: Full Test Output
-```
-🚀 Starting Calendar-Goal Analysis API Tests
-
-Running 3 tests
-✔ Edge case - no goals defined (67.8ms)
-✔ Multi-tenancy data isolation (205.9ms)
-✔ Full analysis flow (passed)
-
-❌ Total Failed Tests: 0
-```
-
-### Example: Database Objects (if applicable)
-```javascript
-{
-  _id: ObjectId("68e81da2a87a1a0f91589023"),
-  executive_id: "demo-exec-001",
-  title: "Increase Enterprise Sales by 30%",
-  timeframe: "QUARTERLY",
-  priority: 9,
-  status: "IN_PROGRESS"
-}
-```
-
-### Example: API Request/Response (if applicable)
-**Request:**
-```http
-GET /executive-goals/calendar-analysis?timeframe=backward&period=7
-Headers:
-  x-executive-id: demo-exec-001
-```
-
-**Response (200 OK):**
-```json
-{
-  "success": true,
-  "analysis": {
-    "executive_id": "demo-exec-001",
-    "total_calendar_hours": 7.5,
-    "goal_breakdown": [
-      {
-        "goal_id": "68e81da2a87a1a0f91589025",
-        "goal_title": "Launch AI Product Line",
-        "total_hours": 2.5,
-        "percentage": 33.3,
-        "meeting_ids": ["event-002", "event-007"]
-      }
-    ]
-  }
-}
-```
-
-## New Files/Functions Created
- - Table with the following columns
-    - File/Function Name
-    - Purpose
-    - Who is using/importing/calling it
-    - Is it actually used? (Yes/No - if No, explain why it exists)
-
-## New Tests Added
- - Added all tests suggested in tech spec: Yes/No
- - Table with the following columns
-    - Test Case Name
-    - What is test case validating
-    - Test Result (pass vs fail)
-    - Failure Analysis (if fail)
-
-## Existing Test Suites Run
- - Table with following columns
-    - Test Suite
-    - Was it Run (if not, why not - it's ok to not run a suite if there is no impact of your work to it as covered in agent-testing-guidelines.md)
-    - Failing Tests
-    - Failure Analysis (if any tests fail)
-
-   
-## Pre-Completion Reflection
-
-[Include reflection analysis here following `.ai-agents/rules/mandatory-pre-completion-reflection.md`]
-
-✅ Reflection Phase 1 (Claim Verification) completed: YES/NO
-✅ Reflection Phase 2 (Risk Analysis) completed: YES/NO
-✅ Reflection Phase 3 (Validation Plan Check) completed: YES/NO
-✅ Reflection Phase 4 (Self-Audit) completed: YES/NO
-✅ All blockers from reflection addressed: YES/NO
-✅ Confidence level: X% (must be ≥ 90% to proceed)
-
-**Reflection Summary:**
-[Brief summary of key findings from reflection]
-
-## Continous Learning
- - Table with following columns
-    - Learning
+# Feature: <Title>
+Issue: #<issue>  
+Tech Spec: <Link to tech spec>
+PR: <Link to PR>
+
+## Completeness Evidence
+ - All phases of tech spec complete: Yes/No 
+ - Issue tagged with label `phase:impl`: Yes/No
+ - Issue tagged with label `status:needs-review`: Yes/No
+ - All files committed/synced to branch: Yes/No
+ - Table with following columns 
+   - PR Comment
+   - How Addressed
+
+## Implementation Quality Checkpoints
+ - [ ] Code complexity reviewed (no overengineering)
+ - [ ] No resource waste (excessive retries, delays, workarounds)
+ - [ ] Solution based on proven prototype from design phase
+ - [ ] All new files/functions are actually used
+
+## Validation Evidence
+ - Complete validation performed as suggested in tech spec: Yes/No
+ - **IMPORTANT**: Post full test output (not just "tests passing ✅")
+ - Table with following columns
+    - Validation Step (manual vs automated)
+    - Validation Result (pass vs fail)
+    - Failure Analysis (if fail)
+
+### Example: Full Test Output
+```
+🚀 Starting Calendar-Goal Analysis API Tests
+
+Running 3 tests
+✔ Edge case - no goals defined (67.8ms)
+✔ Multi-tenancy data isolation (205.9ms)
+✔ Full analysis flow (passed)
+
+❌ Total Failed Tests: 0
+```
+
+### Example: Database Objects (if applicable)
+```javascript
+{
+  _id: ObjectId("68e81da2a87a1a0f91589023"),
+  executive_id: "demo-exec-001",
+  title: "Increase Enterprise Sales by 30%",
+  timeframe: "QUARTERLY",
+  priority: 9,
+  status: "IN_PROGRESS"
+}
+```
+
+### Example: API Request/Response (if applicable)
+**Request:**
+```http
+GET /executive-goals/calendar-analysis?timeframe=backward&period=7
+Headers:
+  x-executive-id: demo-exec-001
+```
+
+**Response (200 OK):**
+```json
+{
+  "success": true,
+  "analysis": {
+    "executive_id": "demo-exec-001",
+    "total_calendar_hours": 7.5,
+    "goal_breakdown": [
+      {
+        "goal_id": "68e81da2a87a1a0f91589025",
+        "goal_title": "Launch AI Product Line",
+        "total_hours": 2.5,
+        "percentage": 33.3,
+        "meeting_ids": ["event-002", "event-007"]
+      }
+    ]
+  }
+}
+```
+
+## New Files/Functions Created
+ - Table with the following columns
+    - File/Function Name
+    - Purpose
+    - Who is using/importing/calling it
+    - Is it actually used? (Yes/No - if No, explain why it exists)
+
+## New Tests Added
+ - Added all tests suggested in tech spec: Yes/No
+ - Table with the following columns
+    - Test Case Name
+    - What is test case validating
+    - Test Result (pass vs fail)
+    - Failure Analysis (if fail)
+
+## Existing Test Suites Run
+ - Table with following columns
+    - Test Suite
+    - Was it Run (if not, why not - it's ok to not run a suite if there is no impact of your work to it as covered in agent-testing-guidelines.md)
+    - Failing Tests
+    - Failure Analysis (if any tests fail)
+
+   
+## Pre-Completion Reflection
+
+[Include reflection analysis here following `get_fraim_file({ path: "rules/mandatory-pre-completion-reflection.md" })`]
+
+✅ Reflection Phase 1 (Claim Verification) completed: YES/NO
+✅ Reflection Phase 2 (Risk Analysis) completed: YES/NO
+✅ Reflection Phase 3 (Validation Plan Check) completed: YES/NO
+✅ Reflection Phase 4 (Self-Audit) completed: YES/NO
+✅ All blockers from reflection addressed: YES/NO
+✅ Confidence level: X% (must be ≥ 90% to proceed)
+
+**Reflection Summary:**
+[Brief summary of key findings from reflection]
+
+## Continous Learning
+ - Table with following columns
+    - Learning
     - Agent Rule Updates (what agent rule file was updated to ensure the learning is durable)