[P1] Implement Project.get_status() comprehensive status gathering

[frankbria]

Overview

The get_status() method returns minimal hardcoded status instead of gathering comprehensive project state.

Current State

File: codeframe/core/project.py lines 131-139

def get_status(self) -> Dict[str, Any]:
    """Get current project status."""
    # TODO: Implement comprehensive status gathering
    return {
        "id": self.id,
        "name": self.name,
        "status": self._status.value,
        "created_at": self.created_at.isoformat() if self.created_at else None,
    }

Expected Behavior

Comprehensive status should include:

• Project metadata (id, name, status, timestamps)
• Task statistics (total, completed, in_progress, blocked)
• Agent status (active, idle, assigned tasks)
• Progress percentage
• Recent activity (last task completed, time elapsed)
• Blocker count
• Quality metrics (test pass rate, coverage)

Implementation Requirements

1. Query database for task statistics
2. Query database for agent status
3. Calculate progress percentage from tasks
4. Get recent activity from timestamps
5. Count active blockers
6. Get latest quality metrics from quality_tracker

Return Format

{
    "id": 1,
    "name": "My Project",
    "status": "active",
    "created_at": "2025-11-20T10:00:00",
    "tasks": {
        "total": 40,
        "completed": 27,
        "in_progress": 5,
        "blocked": 2,
        "pending": 6
    },
    "agents": {
        "active": 3,
        "idle": 1,
        "total": 4
    },
    "progress_pct": 67.5,
    "blockers": 2,
    "quality": {
        "test_pass_rate": 100.0,
        "coverage_pct": 87.5
    },
    "last_activity": "2 minutes ago"
}

Acceptance Criteria

• Status includes task statistics
• Status includes agent information
• Progress percentage calculated correctly
• Recent activity shown with timestamps
• Blocker count accurate
• Quality metrics included

Priority

P1 - Critical: Dashboard relies on this for displaying project state.

References

• User Documentation: CODEFRAME_USER_DOCUMENTATION.md lines 159-167
• Issues Analysis: CODEFRAME_ISSUES_ANALYSIS.md lines 131-139

[traycerai]

Plan

Observations

The Project.get_status() method in file:codeframe/core/project.py (lines 130-139) currently returns minimal hardcoded data. The codebase has a comprehensive Database class with methods for querying tasks, agents, blockers, and activity. The QualityTracker class provides quality metrics. Task statuses include PENDING, ASSIGNED, IN_PROGRESS, BLOCKED, COMPLETED, and FAILED. Agent information is stored in the agents table with status fields. The database stores project records with IDs that need to be retrieved by project name.

Approach

The implementation will query the database for comprehensive project state by: (1) retrieving the project ID from the database using the project name, (2) aggregating task statistics by status, (3) querying agent information and determining active/idle states, (4) calculating progress percentage from completed vs total tasks, (5) counting pending blockers, (6) retrieving quality metrics from the QualityTracker, and (7) formatting the most recent activity timestamp. This approach leverages existing database methods and follows the codebase's patterns for data aggregation.

Implementation Steps

1. Retrieve Project ID from Database

In file:codeframe/core/project.py, modify the get_status() method to first retrieve the project ID from the database using the project name stored in self.config:

• Query the database using SELECT id, name, status, created_at FROM projects WHERE name = ? with the project name from self.config.load().project_name
• Handle the case where the project is not found in the database (return minimal status with warning)
• Store the retrieved project ID for subsequent queries

2. Query Task Statistics

Aggregate task counts by status using the get_project_tasks() method:

• Call self.db.get_project_tasks(project_id) to retrieve all tasks
• Count tasks by status: iterate through tasks and count occurrences of each TaskStatus value
• Calculate totals for: total, completed, in_progress, blocked, pending (PENDING + ASSIGNED)
• Note: FAILED tasks should be included in the total but tracked separately

3. Query Agent Information

Retrieve agent data using the get_agents_for_project() method:

• Call self.db.get_agents_for_project(project_id, active_only=True) to get active agents
• Count agents by status field:
  • active: agents with status field indicating active work or with current_task_id not null
  • idle: agents with status field indicating idle or with current_task_id null
  • total: total count of all agents returned
• Handle the case where no agents are assigned (all counts = 0)

4. Calculate Progress Percentage

Compute progress based on completed tasks:

• Use the task statistics from step 2
• Calculate: progress_pct = (completed_tasks / total_tasks * 100) if total_tasks > 0, else 0.0
• Round to 1 decimal place for display consistency

5. Count Active Blockers

Query blocker count using the list_blockers() method:

• Call self.db.list_blockers(project_id, status='PENDING') to get pending blockers
• Extract the pending_count from the returned dictionary
• This represents the blockers field in the status response

6. Retrieve Quality Metrics

Access quality metrics from the QualityTracker:

• Initialize QualityTracker with project_path=self.project_dir
• Call tracker.get_stats() to retrieve quality data
• Extract test_pass_rate and coverage_pct from the current metrics
• Handle the case where no quality data exists (return None or default values like 0.0)
• Format as: {"test_pass_rate": float, "coverage_pct": float}

7. Format Last Activity Timestamp

Retrieve and format the most recent activity:

• Call self.db.get_recent_activity(project_id, limit=1) to get the most recent activity
• If activity exists, extract the timestamp field
• Use a time formatting helper similar to _format_time_ago() from file:codeframe/agents/lead_agent.py (lines 1553-1583)
• Format as "X minutes ago", "X hours ago", "X days ago", or "just now"
• If no activity exists, return "No activity yet"

8. Construct and Return Status Dictionary

Build the comprehensive status dictionary with all gathered data:

{
    "id": project_id,
    "name": project_name,
    "status": self._status.value,
    "created_at": created_at_iso_string,
    "tasks": {
        "total": total_tasks,
        "completed": completed_tasks,
        "in_progress": in_progress_tasks,
        "blocked": blocked_tasks,
        "pending": pending_tasks
    },
    "agents": {
        "active": active_agents,
        "idle": idle_agents,
        "total": total_agents
    },
    "progress_pct": progress_percentage,
    "blockers": pending_blocker_count,
    "quality": {
        "test_pass_rate": test_pass_rate,
        "coverage_pct": coverage_percentage
    },
    "last_activity": formatted_time_string
}

9. Error Handling

Add appropriate error handling throughout:

• Handle database connection errors (check if self.db is None)
• Handle missing project in database (return minimal status)
• Handle empty result sets gracefully (return 0 counts, empty lists)
• Log warnings for missing data but don't fail the entire operation
• Ensure the method never raises exceptions, always returns a valid dictionary

Data Flow Diagram

sequenceDiagram
    participant Caller
    participant Project
    participant Database
    participant QualityTracker
    
    Caller->>Project: get_status()
    Project->>Database: Query project by name
    Database-->>Project: project_id, metadata
    
    Project->>Database: get_project_tasks(project_id)
    Database-->>Project: List of tasks
    Project->>Project: Aggregate task statistics
    
    Project->>Database: get_agents_for_project(project_id)
    Database-->>Project: List of agents
    Project->>Project: Count active/idle agents
    
    Project->>Database: list_blockers(project_id, 'PENDING')
    Database-->>Project: Blocker counts
    
    Project->>Database: get_recent_activity(project_id, 1)
    Database-->>Project: Most recent activity
    Project->>Project: Format timestamp
    
    Project->>QualityTracker: get_stats()
    QualityTracker-->>Project: Quality metrics
    
    Project->>Project: Calculate progress percentage
    Project->>Project: Build status dictionary
    Project-->>Caller: Comprehensive status dict

Loading

Key Implementation Details

Component	Method/Field	Purpose
Database query	SELECT id FROM projects WHERE name = ?	Get project ID by name
Task aggregation	get_project_tasks(project_id)	Retrieve all tasks for counting
Agent query	get_agents_for_project(project_id, True)	Get active agents with status
Blocker count	list_blockers(project_id, 'PENDING')	Count pending blockers
Activity	get_recent_activity(project_id, 1)	Get most recent activity
Quality metrics	QualityTracker.get_stats()	Retrieve test/coverage metrics
Time formatting	Custom helper function	Format timestamps as "X ago"

Dependencies

• file:codeframe/persistence/database.py - Database methods for querying
• file:codeframe/enforcement/quality_tracker.py - QualityTracker class
• file:codeframe/core/models.py - TaskStatus enum for status values
• datetime module - For timestamp parsing and formatting

Import In IDE

🤖 Prompt for AI Agents

## Observations

The `Project.get_status()` method in `file:codeframe/core/project.py` (lines 130-139) currently returns minimal hardcoded data. The codebase has a comprehensive `Database` class with methods for querying tasks, agents, blockers, and activity. The `QualityTracker` class provides quality metrics. Task statuses include PENDING, ASSIGNED, IN_PROGRESS, BLOCKED, COMPLETED, and FAILED. Agent information is stored in the `agents` table with status fields. The database stores project records with IDs that need to be retrieved by project name.

## Approach

The implementation will query the database for comprehensive project state by: (1) retrieving the project ID from the database using the project name, (2) aggregating task statistics by status, (3) querying agent information and determining active/idle states, (4) calculating progress percentage from completed vs total tasks, (5) counting pending blockers, (6) retrieving quality metrics from the QualityTracker, and (7) formatting the most recent activity timestamp. This approach leverages existing database methods and follows the codebase's patterns for data aggregation.

## Implementation Steps

### 1. Retrieve Project ID from Database

In `file:codeframe/core/project.py`, modify the `get_status()` method to first retrieve the project ID from the database using the project name stored in `self.config`:

- Query the database using `SELECT id, name, status, created_at FROM projects WHERE name = ?` with the project name from `self.config.load().project_name`
- Handle the case where the project is not found in the database (return minimal status with warning)
- Store the retrieved project ID for subsequent queries

### 2. Query Task Statistics

Aggregate task counts by status using the `get_project_tasks()` method:

- Call `self.db.get_project_tasks(project_id)` to retrieve all tasks
- Count tasks by status: iterate through tasks and count occurrences of each `TaskStatus` value
- Calculate totals for: `total`, `completed`, `in_progress`, `blocked`, `pending` (PENDING + ASSIGNED)
- Note: FAILED tasks should be included in the total but tracked separately

### 3. Query Agent Information

Retrieve agent data using the `get_agents_for_project()` method:

- Call `self.db.get_agents_for_project(project_id, active_only=True)` to get active agents
- Count agents by status field:
  - `active`: agents with `status` field indicating active work or with `current_task_id` not null
  - `idle`: agents with `status` field indicating idle or with `current_task_id` null
  - `total`: total count of all agents returned
- Handle the case where no agents are assigned (all counts = 0)

### 4. Calculate Progress Percentage

Compute progress based on completed tasks:

- Use the task statistics from step 2
- Calculate: `progress_pct = (completed_tasks / total_tasks * 100)` if `total_tasks > 0`, else `0.0`
- Round to 1 decimal place for display consistency

### 5. Count Active Blockers

Query blocker count using the `list_blockers()` method:

- Call `self.db.list_blockers(project_id, status='PENDING')` to get pending blockers
- Extract the `pending_count` from the returned dictionary
- This represents the `blockers` field in the status response

### 6. Retrieve Quality Metrics

Access quality metrics from the QualityTracker:

- Initialize `QualityTracker` with `project_path=self.project_dir`
- Call `tracker.get_stats()` to retrieve quality data
- Extract `test_pass_rate` and `coverage_pct` from the current metrics
- Handle the case where no quality data exists (return `None` or default values like `0.0`)
- Format as: `{"test_pass_rate": float, "coverage_pct": float}`

### 7. Format Last Activity Timestamp

Retrieve and format the most recent activity:

- Call `self.db.get_recent_activity(project_id, limit=1)` to get the most recent activity
- If activity exists, extract the `timestamp` field
- Use a time formatting helper similar to `_format_time_ago()` from `file:codeframe/agents/lead_agent.py` (lines 1553-1583)
- Format as "X minutes ago", "X hours ago", "X days ago", or "just now"
- If no activity exists, return `"No activity yet"`

### 8. Construct and Return Status Dictionary

Build the comprehensive status dictionary with all gathered data:

```python
{
    "id": project_id,
    "name": project_name,
    "status": self._status.value,
    "created_at": created_at_iso_string,
    "tasks": {
        "total": total_tasks,
        "completed": completed_tasks,
        "in_progress": in_progress_tasks,
        "blocked": blocked_tasks,
        "pending": pending_tasks
    },
    "agents": {
        "active": active_agents,
        "idle": idle_agents,
        "total": total_agents
    },
    "progress_pct": progress_percentage,
    "blockers": pending_blocker_count,
    "quality": {
        "test_pass_rate": test_pass_rate,
        "coverage_pct": coverage_percentage
    },
    "last_activity": formatted_time_string
}
```

### 9. Error Handling

Add appropriate error handling throughout:

- Handle database connection errors (check if `self.db` is None)
- Handle missing project in database (return minimal status)
- Handle empty result sets gracefully (return 0 counts, empty lists)
- Log warnings for missing data but don't fail the entire operation
- Ensure the method never raises exceptions, always returns a valid dictionary

## Data Flow Diagram

```mermaid
sequenceDiagram
    participant Caller
    participant Project
    participant Database
    participant QualityTracker
    
    Caller->>Project: get_status()
    Project->>Database: Query project by name
    Database-->>Project: project_id, metadata
    
    Project->>Database: get_project_tasks(project_id)
    Database-->>Project: List of tasks
    Project->>Project: Aggregate task statistics
    
    Project->>Database: get_agents_for_project(project_id)
    Database-->>Project: List of agents
    Project->>Project: Count active/idle agents
    
    Project->>Database: list_blockers(project_id, 'PENDING')
    Database-->>Project: Blocker counts
    
    Project->>Database: get_recent_activity(project_id, 1)
    Database-->>Project: Most recent activity
    Project->>Project: Format timestamp
    
    Project->>QualityTracker: get_stats()
    QualityTracker-->>Project: Quality metrics
    
    Project->>Project: Calculate progress percentage
    Project->>Project: Build status dictionary
    Project-->>Caller: Comprehensive status dict
```

## Key Implementation Details

| Component | Method/Field | Purpose |
|-----------|-------------|---------|
| Database query | `SELECT id FROM projects WHERE name = ?` | Get project ID by name |
| Task aggregation | `get_project_tasks(project_id)` | Retrieve all tasks for counting |
| Agent query | `get_agents_for_project(project_id, True)` | Get active agents with status |
| Blocker count | `list_blockers(project_id, 'PENDING')` | Count pending blockers |
| Activity | `get_recent_activity(project_id, 1)` | Get most recent activity |
| Quality metrics | `QualityTracker.get_stats()` | Retrieve test/coverage metrics |
| Time formatting | Custom helper function | Format timestamps as "X ago" |

## Dependencies

- `file:codeframe/persistence/database.py` - Database methods for querying
- `file:codeframe/enforcement/quality_tracker.py` - QualityTracker class
- `file:codeframe/core/models.py` - TaskStatus enum for status values
- `datetime` module - For timestamp parsing and formatting

---

Execution Information

Branch: main
Commit: 1a87e4e

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

_{You can configure auto-planning by selecting labels in the issue_enrichment configuration.}

🔗 Similar Issues

Related Issues

• [P1] Replace mock data with database queries in GET /api/projects/{id}/tasks #104
• [P1] Implement Project.start() with Lead Agent initialization #102
• [P1] Implement Project.pause() with flash save mechanism #103

👤 Suggested Assignees

• frankbria

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

New Plan

Observations

The Project.get_status() method in file:codeframe/core/project.py (lines 130-139) currently returns minimal hardcoded data. The codebase has a comprehensive Database class with methods for querying tasks, agents, blockers, and activity. The QualityTracker class provides quality metrics. Task statuses include PENDING, ASSIGNED, IN_PROGRESS, BLOCKED, COMPLETED, and FAILED. Agent information is stored in the agents table with status fields. The database stores project records with IDs that need to be retrieved by project name.

Approach

The implementation will query the database for comprehensive project state by: (1) retrieving the project ID from the database using the project name, (2) aggregating task statistics by status, (3) querying agent information and determining active/idle states, (4) calculating progress percentage from completed vs total tasks, (5) counting pending blockers, (6) retrieving quality metrics from the QualityTracker, and (7) formatting the most recent activity timestamp. This approach leverages existing database methods and follows the codebase's patterns for data aggregation.

Implementation Steps

1. Retrieve Project ID from Database

In file:codeframe/core/project.py, modify the get_status() method to first retrieve the project ID from the database using the project name stored in self.config:

• Query the database using SELECT id, name, status, created_at FROM projects WHERE name = ? with the project name from self.config.load().project_name
• Handle the case where the project is not found in the database (return minimal status with warning)
• Store the retrieved project ID for subsequent queries

2. Query Task Statistics

Aggregate task counts by status using the get_project_tasks() method:

• Call self.db.get_project_tasks(project_id) to retrieve all tasks
• Count tasks by status: iterate through tasks and count occurrences of each TaskStatus value
• Calculate totals for: total, completed, in_progress, blocked, pending (PENDING + ASSIGNED)
• Note: FAILED tasks should be included in the total but tracked separately

3. Query Agent Information

Retrieve agent data using the get_agents_for_project() method:

• Call self.db.get_agents_for_project(project_id, active_only=True) to get active agents
• Count agents by status field:
  • active: agents with status field indicating active work or with current_task_id not null
  • idle: agents with status field indicating idle or with current_task_id null
  • total: total count of all agents returned
• Handle the case where no agents are assigned (all counts = 0)

4. Calculate Progress Percentage

Compute progress based on completed tasks:

• Use the task statistics from step 2
• Calculate: progress_pct = (completed_tasks / total_tasks * 100) if total_tasks > 0, else 0.0
• Round to 1 decimal place for display consistency

5. Count Active Blockers

Query blocker count using the list_blockers() method:

• Call self.db.list_blockers(project_id, status='PENDING') to get pending blockers
• Extract the pending_count from the returned dictionary
• This represents the blockers field in the status response

6. Retrieve Quality Metrics

Access quality metrics from the QualityTracker:

• Initialize QualityTracker with project_path=self.project_dir
• Call tracker.get_stats() to retrieve quality data
• Extract test_pass_rate and coverage_pct from the current metrics
• Handle the case where no quality data exists (return None or default values like 0.0)
• Format as: {"test_pass_rate": float, "coverage_pct": float}

7. Format Last Activity Timestamp

Retrieve and format the most recent activity:

• Call self.db.get_recent_activity(project_id, limit=1) to get the most recent activity
• If activity exists, extract the timestamp field
• Use a time formatting helper similar to _format_time_ago() from file:codeframe/agents/lead_agent.py (lines 1553-1583)
• Format as "X minutes ago", "X hours ago", "X days ago", or "just now"
• If no activity exists, return "No activity yet"

8. Construct and Return Status Dictionary

Build the comprehensive status dictionary with all gathered data:

{
    "id": project_id,
    "name": project_name,
    "status": self._status.value,
    "created_at": created_at_iso_string,
    "tasks": {
        "total": total_tasks,
        "completed": completed_tasks,
        "in_progress": in_progress_tasks,
        "blocked": blocked_tasks,
        "pending": pending_tasks
    },
    "agents": {
        "active": active_agents,
        "idle": idle_agents,
        "total": total_agents
    },
    "progress_pct": progress_percentage,
    "blockers": pending_blocker_count,
    "quality": {
        "test_pass_rate": test_pass_rate,
        "coverage_pct": coverage_percentage
    },
    "last_activity": formatted_time_string
}

9. Error Handling

Add appropriate error handling throughout:

• Handle database connection errors (check if self.db is None)
• Handle missing project in database (return minimal status)
• Handle empty result sets gracefully (return 0 counts, empty lists)
• Log warnings for missing data but don't fail the entire operation
• Ensure the method never raises exceptions, always returns a valid dictionary

Data Flow Diagram

sequenceDiagram
    participant Caller
    participant Project
    participant Database
    participant QualityTracker
    
    Caller->>Project: get_status()
    Project->>Database: Query project by name
    Database-->>Project: project_id, metadata
    
    Project->>Database: get_project_tasks(project_id)
    Database-->>Project: List of tasks
    Project->>Project: Aggregate task statistics
    
    Project->>Database: get_agents_for_project(project_id)
    Database-->>Project: List of agents
    Project->>Project: Count active/idle agents
    
    Project->>Database: list_blockers(project_id, 'PENDING')
    Database-->>Project: Blocker counts
    
    Project->>Database: get_recent_activity(project_id, 1)
    Database-->>Project: Most recent activity
    Project->>Project: Format timestamp
    
    Project->>QualityTracker: get_stats()
    QualityTracker-->>Project: Quality metrics
    
    Project->>Project: Calculate progress percentage
    Project->>Project: Build status dictionary
    Project-->>Caller: Comprehensive status dict

Loading

Key Implementation Details

Component	Method/Field	Purpose
Database query	SELECT id FROM projects WHERE name = ?	Get project ID by name
Task aggregation	get_project_tasks(project_id)	Retrieve all tasks for counting
Agent query	get_agents_for_project(project_id, True)	Get active agents with status
Blocker count	list_blockers(project_id, 'PENDING')	Count pending blockers
Activity	get_recent_activity(project_id, 1)	Get most recent activity
Quality metrics	QualityTracker.get_stats()	Retrieve test/coverage metrics
Time formatting	Custom helper function	Format timestamps as "X ago"

Dependencies

• file:codeframe/persistence/database.py - Database methods for querying
• file:codeframe/enforcement/quality_tracker.py - QualityTracker class
• file:codeframe/core/models.py - TaskStatus enum for status values
• datetime module - For timestamp parsing and formatting

Import In IDE

🤖 Prompt for AI Agents

## Observations

The `Project.get_status()` method in `file:codeframe/core/project.py` (lines 130-139) currently returns minimal hardcoded data. The codebase has a comprehensive `Database` class with methods for querying tasks, agents, blockers, and activity. The `QualityTracker` class provides quality metrics. Task statuses include PENDING, ASSIGNED, IN_PROGRESS, BLOCKED, COMPLETED, and FAILED. Agent information is stored in the `agents` table with status fields. The database stores project records with IDs that need to be retrieved by project name.

## Approach

The implementation will query the database for comprehensive project state by: (1) retrieving the project ID from the database using the project name, (2) aggregating task statistics by status, (3) querying agent information and determining active/idle states, (4) calculating progress percentage from completed vs total tasks, (5) counting pending blockers, (6) retrieving quality metrics from the QualityTracker, and (7) formatting the most recent activity timestamp. This approach leverages existing database methods and follows the codebase's patterns for data aggregation.

## Implementation Steps

### 1. Retrieve Project ID from Database

In `file:codeframe/core/project.py`, modify the `get_status()` method to first retrieve the project ID from the database using the project name stored in `self.config`:

- Query the database using `SELECT id, name, status, created_at FROM projects WHERE name = ?` with the project name from `self.config.load().project_name`
- Handle the case where the project is not found in the database (return minimal status with warning)
- Store the retrieved project ID for subsequent queries

### 2. Query Task Statistics

Aggregate task counts by status using the `get_project_tasks()` method:

- Call `self.db.get_project_tasks(project_id)` to retrieve all tasks
- Count tasks by status: iterate through tasks and count occurrences of each `TaskStatus` value
- Calculate totals for: `total`, `completed`, `in_progress`, `blocked`, `pending` (PENDING + ASSIGNED)
- Note: FAILED tasks should be included in the total but tracked separately

### 3. Query Agent Information

Retrieve agent data using the `get_agents_for_project()` method:

- Call `self.db.get_agents_for_project(project_id, active_only=True)` to get active agents
- Count agents by status field:
  - `active`: agents with `status` field indicating active work or with `current_task_id` not null
  - `idle`: agents with `status` field indicating idle or with `current_task_id` null
  - `total`: total count of all agents returned
- Handle the case where no agents are assigned (all counts = 0)

### 4. Calculate Progress Percentage

Compute progress based on completed tasks:

- Use the task statistics from step 2
- Calculate: `progress_pct = (completed_tasks / total_tasks * 100)` if `total_tasks > 0`, else `0.0`
- Round to 1 decimal place for display consistency

### 5. Count Active Blockers

Query blocker count using the `list_blockers()` method:

- Call `self.db.list_blockers(project_id, status='PENDING')` to get pending blockers
- Extract the `pending_count` from the returned dictionary
- This represents the `blockers` field in the status response

### 6. Retrieve Quality Metrics

Access quality metrics from the QualityTracker:

- Initialize `QualityTracker` with `project_path=self.project_dir`
- Call `tracker.get_stats()` to retrieve quality data
- Extract `test_pass_rate` and `coverage_pct` from the current metrics
- Handle the case where no quality data exists (return `None` or default values like `0.0`)
- Format as: `{"test_pass_rate": float, "coverage_pct": float}`

### 7. Format Last Activity Timestamp

Retrieve and format the most recent activity:

- Call `self.db.get_recent_activity(project_id, limit=1)` to get the most recent activity
- If activity exists, extract the `timestamp` field
- Use a time formatting helper similar to `_format_time_ago()` from `file:codeframe/agents/lead_agent.py` (lines 1553-1583)
- Format as "X minutes ago", "X hours ago", "X days ago", or "just now"
- If no activity exists, return `"No activity yet"`

### 8. Construct and Return Status Dictionary

Build the comprehensive status dictionary with all gathered data:

```python
{
    "id": project_id,
    "name": project_name,
    "status": self._status.value,
    "created_at": created_at_iso_string,
    "tasks": {
        "total": total_tasks,
        "completed": completed_tasks,
        "in_progress": in_progress_tasks,
        "blocked": blocked_tasks,
        "pending": pending_tasks
    },
    "agents": {
        "active": active_agents,
        "idle": idle_agents,
        "total": total_agents
    },
    "progress_pct": progress_percentage,
    "blockers": pending_blocker_count,
    "quality": {
        "test_pass_rate": test_pass_rate,
        "coverage_pct": coverage_percentage
    },
    "last_activity": formatted_time_string
}
```

### 9. Error Handling

Add appropriate error handling throughout:

- Handle database connection errors (check if `self.db` is None)
- Handle missing project in database (return minimal status)
- Handle empty result sets gracefully (return 0 counts, empty lists)
- Log warnings for missing data but don't fail the entire operation
- Ensure the method never raises exceptions, always returns a valid dictionary

## Data Flow Diagram

```mermaid
sequenceDiagram
    participant Caller
    participant Project
    participant Database
    participant QualityTracker
    
    Caller->>Project: get_status()
    Project->>Database: Query project by name
    Database-->>Project: project_id, metadata
    
    Project->>Database: get_project_tasks(project_id)
    Database-->>Project: List of tasks
    Project->>Project: Aggregate task statistics
    
    Project->>Database: get_agents_for_project(project_id)
    Database-->>Project: List of agents
    Project->>Project: Count active/idle agents
    
    Project->>Database: list_blockers(project_id, 'PENDING')
    Database-->>Project: Blocker counts
    
    Project->>Database: get_recent_activity(project_id, 1)
    Database-->>Project: Most recent activity
    Project->>Project: Format timestamp
    
    Project->>QualityTracker: get_stats()
    QualityTracker-->>Project: Quality metrics
    
    Project->>Project: Calculate progress percentage
    Project->>Project: Build status dictionary
    Project-->>Caller: Comprehensive status dict
```

## Key Implementation Details

| Component | Method/Field | Purpose |
|-----------|-------------|---------|
| Database query | `SELECT id FROM projects WHERE name = ?` | Get project ID by name |
| Task aggregation | `get_project_tasks(project_id)` | Retrieve all tasks for counting |
| Agent query | `get_agents_for_project(project_id, True)` | Get active agents with status |
| Blocker count | `list_blockers(project_id, 'PENDING')` | Count pending blockers |
| Activity | `get_recent_activity(project_id, 1)` | Get most recent activity |
| Quality metrics | `QualityTracker.get_stats()` | Retrieve test/coverage metrics |
| Time formatting | Custom helper function | Format timestamps as "X ago" |

## Dependencies

- `file:codeframe/persistence/database.py` - Database methods for querying
- `file:codeframe/enforcement/quality_tracker.py` - QualityTracker class
- `file:codeframe/core/models.py` - TaskStatus enum for status values
- `datetime` module - For timestamp parsing and formatting

---

Execution Information

Branch: main
Commit: 1a87e4e