[Future] Parse issue dependencies from database storage

[frankbria]

Overview

Issue dependencies are not parsed from database storage, always returning empty array.

Current State

File: codeframe/persistence/database.py line 1941

"depends_on": [],  # TODO: Parse from database if stored

Expected Behavior

• Store issue dependencies in database (junction table)
• Parse dependencies when loading issues
• Return list of issue IDs this issue depends on
• Support multiple dependency types (blocks, related, etc.)

Implementation Requirements

1. Create issue_dependencies table if not exists
2. Store dependencies on issue creation
3. Parse dependencies when loading issues
4. Return dependency list in Issue object

Database Schema

CREATE TABLE IF NOT EXISTS issue_dependencies (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    issue_id INTEGER NOT NULL,
    depends_on_issue_id INTEGER NOT NULL,
    dependency_type TEXT DEFAULT 'blocks',  -- blocks, related, parent-child
    created_at TEXT NOT NULL,
    FOREIGN KEY (issue_id) REFERENCES issues(id),
    FOREIGN KEY (depends_on_issue_id) REFERENCES issues(id),
    UNIQUE(issue_id, depends_on_issue_id, dependency_type)
);

Example Usage

# Create issue with dependencies
issue = Issue(
    issue_number="2.1",
    title="User authentication",
    depends_on=["1.5", "1.8"]  # Depends on these issues
)
db.save_issue(issue)

# Load issue with dependencies
loaded = db.get_issue_by_number("2.1")
print(loaded.depends_on)  # ["1.5", "1.8"]

Acceptance Criteria

• issue_dependencies table created
• Dependencies saved on issue creation
• Dependencies parsed when loading issues
• Multiple dependency types supported
• Circular dependencies detected and prevented
• Unit tests verify dependency storage/retrieval

Priority

P3 - Advanced: Useful for complex project planning, but not critical for MVP.

References

• File: codeframe/persistence/database.py line 1941

[traycerai]

Plan

Observations

The codebase currently has a TODO comment in file:codeframe/persistence/repositories/issue_repository.py at line 169 that returns an empty array for issue dependencies. The Issue dataclass in file:codeframe/core/models.py does not have a depends_on field. However, the system already implements a similar pattern for task dependencies using a junction table (task_dependencies) with supporting methods. The schema manager in file:codeframe/persistence/schema_manager.py creates all database tables but lacks an issue_dependencies table. The implementation should follow the existing task dependency pattern for consistency.

This feature is marked as "Future" priority, indicating it is an optimization for complex project planning that is not required for the current workflow (Steps 1-10). The implementation should be designed for eventual integration without blocking current development.

Approach

The implementation will follow the established task dependency pattern by creating an issue_dependencies junction table, adding a depends_on field to the Issue model, implementing CRUD methods in the issue repository, and updating the schema manager. Dependencies will be stored as issue numbers (strings like "1.5", "2.1") rather than IDs for better usability, matching the GitHub issue specification. The solution will include circular dependency detection, proper indexing for performance, and comprehensive test coverage following the existing test patterns in file:tests/persistence/test_database_issues.py. This implementation is designed as a self-contained feature that can be integrated when prioritized without impacting current workflows.

Implementation Steps

1. Update Issue Model

File: file:codeframe/core/models.py

Add a depends_on field to the Issue dataclass (after line 195):

• Add depends_on: List[str] = field(default_factory=list) to store issue numbers this issue depends on
• Update the to_dict() method to include the depends_on field in serialization
• This field will be populated from the issue_dependencies junction table when issues are loaded

2. Create Issue Dependencies Table

File: file:codeframe/persistence/schema_manager.py

In the _create_issue_task_tables() method (after the task_dependencies table creation at line 309):

• Add SQL to create issue_dependencies table with columns: id, issue_id, depends_on_issue_id, dependency_type, created_at
• Include UNIQUE constraint on (issue_id, depends_on_issue_id, dependency_type) to prevent duplicates
• Add foreign key constraints referencing issues(id) with CASCADE delete on both foreign keys

In the _create_indexes() method (after the task_dependencies indexes at line 747):

• Create index on issue_dependencies(issue_id) for fast lookup of dependencies
• Create index on issue_dependencies(depends_on_issue_id) for reverse dependency queries

3. Implement Issue Dependency Methods

File: file:codeframe/persistence/repositories/issue_repository.py

Add new methods following the task dependency pattern from file:codeframe/persistence/repositories/task_repository.py:

Method: add_issue_dependency(issue_id: int, depends_on_issue_id: int, dependency_type: str = 'blocks') -> None

• Validate both issue IDs exist in the database
• Check for circular dependencies by traversing the dependency graph using _detect_circular_dependency()
• Raise ValueError if circular dependency would be created
• Insert into issue_dependencies junction table with the specified dependency_type
• Commit transaction

Method: get_issue_dependencies(issue_id: int) -> List[str]

• Query issue_dependencies table for the given issue_id
• Join with issues table to get issue_numbers
• Return list of issue numbers (strings) that this issue depends on
• Return empty list if issue has no dependencies

Method: get_dependent_issues(issue_id: int) -> List[str]

• Query issue_dependencies table where depends_on_issue_id matches
• Join with issues table to get issue_numbers
• Return list of issue numbers that depend on this issue
• Return empty list if no issues depend on this one

Method: remove_issue_dependency(issue_id: int, depends_on_issue_id: int) -> int

• Delete from issue_dependencies junction table
• Commit transaction
• Return number of rows deleted

Method: clear_all_issue_dependencies(issue_id: int) -> int

• Delete all rows from issue_dependencies where issue_id matches
• Commit transaction
• Return number of rows deleted

Method: _detect_circular_dependency(issue_id: int, depends_on_issue_id: int) -> bool

• Implement depth-first search to detect cycles in the dependency graph
• Return True if adding this dependency would create a cycle
• Return False if dependency is safe to add
• Used by add_issue_dependency() for validation before insertion

4. Update Issue Creation and Retrieval

File: file:codeframe/persistence/repositories/issue_repository.py

Update create_issue() method (around line 40):

• After inserting the issue and obtaining the issue_id, check if the Issue object has depends_on field populated
• For each dependency issue number in the depends_on list, resolve to issue_id and call add_issue_dependency()
• Handle case where dependency issue numbers don't exist by logging a warning (non-blocking for MVP)
• Alternatively, raise ValueError if strict validation is preferred

Update _row_to_issue() method (around line 340):

• After creating the Issue object from the row, call get_issue_dependencies(issue_id) to fetch dependencies
• Set the depends_on field with the returned list of issue numbers
• Return the populated Issue object with dependencies loaded

Update get_issues_with_tasks() method (around line 159):

• Replace the TODO comment at line 159 with actual dependency parsing
• Call get_issue_dependencies(issue_dict["id"]) to get the list of dependency issue numbers
• Assign to "depends_on" key in the formatted issue dictionary

5. Add Database Delegation Methods

File: file:codeframe/persistence/database.py

Add delegation methods to the Database class (following the pattern around line 388):

• add_issue_dependency(issue_id: int, depends_on_issue_id: int, dependency_type: str = 'blocks') -> None - delegates to self.issues.add_issue_dependency()
• get_issue_dependencies(issue_id: int) -> List[str] - delegates to self.issues.get_issue_dependencies()
• get_dependent_issues(issue_id: int) -> List[str] - delegates to self.issues.get_dependent_issues()
• remove_issue_dependency(issue_id: int, depends_on_issue_id: int) -> int - delegates to self.issues.remove_issue_dependency()
• clear_all_issue_dependencies(issue_id: int) -> int - delegates to self.issues.clear_all_issue_dependencies()

These methods provide a clean public API for dependency management while keeping the implementation in the repository layer.

6. Update Allowed Fields Whitelist

File: file:codeframe/persistence/repositories/issue_repository.py

Update ALLOWED_ISSUE_FIELDS set (around line 23):

• Add "depends_on" to the whitelist to allow updating dependencies via update_issue()
• Note: The depends_on field in the whitelist refers to the JSON-stored field; actual dependency management should use the dedicated add_issue_dependency() and remove_issue_dependency() methods

7. Write Comprehensive Tests

File: file:tests/persistence/test_database_issues.py

Add new test class TestIssueDependencies following the pattern of existing test classes:

Test: test_add_issue_dependency()

• Create two issues in the same project
• Add dependency relationship using add_issue_dependency()
• Verify junction table entry exists
• Verify get_issue_dependencies() returns correct issue number

Test: test_get_issue_dependencies_empty()

• Create issue with no dependencies
• Verify get_issue_dependencies() returns empty list

Test: test_get_dependent_issues()

• Create issue A that depends on issue B
• Verify get_dependent_issues(B) returns [A]
• Verify get_dependent_issues(A) returns empty list

Test: test_remove_issue_dependency()

• Add dependency, then remove it using remove_issue_dependency()
• Verify junction table entry is deleted
• Verify get_issue_dependencies() returns empty list

Test: test_clear_all_issue_dependencies()

• Add multiple dependencies to one issue
• Clear all using clear_all_issue_dependencies()
• Verify all removed

Test: test_circular_dependency_detection()

• Create issues A, B, C
• Add A→B, B→C
• Attempt to add C→A (should fail with ValueError)
• Verify error is raised and not inserted

Test: test_create_issue_with_dependencies()

• Create issue with depends_on=["1.5", "1.8"] in constructor
• Verify dependencies are stored correctly in junction table
• Load issue and verify depends_on field is populated

Test: test_load_issue_with_dependencies()

• Create issue with dependencies
• Load via get_issue()
• Verify depends_on field is populated with correct issue numbers

Test: test_dependency_types()

• Add dependencies with different types (blocks, related, parent-child)
• Verify all types are stored and retrieved correctly
• Verify UNIQUE constraint prevents duplicate (issue_id, depends_on_issue_id, dependency_type)

Test: test_issue_dependencies_cascade_delete()

• Create dependency relationship
• Delete parent issue using delete_all_project_issues()
• Verify junction table entries are deleted (CASCADE)

Test: test_nonexistent_dependency_issue()

• Attempt to create issue depending on non-existent issue number
• Verify appropriate error handling (ValueError or warning)

8. Update API Response Format

File: file:codeframe/persistence/repositories/issue_repository.py

Verify the get_issues_with_tasks() method (line 159) now returns populated depends_on arrays instead of empty arrays after implementing step 4. The API response should include the depends_on field with actual issue numbers instead of the current empty array placeholder.

Database Migration Considerations

Since this adds a new table, existing databases will need migration:

• The issue_dependencies table will be created automatically via CREATE TABLE IF NOT EXISTS in _create_issue_task_tables()
• No data migration needed as this is a new feature
• Existing issues will have empty dependency lists by default
• The schema manager's idempotent design ensures safe application to existing databases

Visual Architecture

graph TD
    A[Issue Model] -->|has field| B[depends_on: List str]
    C[issues table] -->|1:N| D[issue_dependencies table]
    D -->|N:1| C
    E[IssueRepository] -->|manages| D
    E -->|CRUD operations| F[add_issue_dependency]
    E -->|CRUD operations| G[get_issue_dependencies]
    E -->|CRUD operations| H[remove_issue_dependency]
    E -->|validation| I[_detect_circular_dependency]
    J[Database class] -->|delegates to| E
    K[API /issues endpoint] -->|calls| J
    L[Tests] -->|verify| E
    L -->|verify| I

Loading

Dependency Flow

sequenceDiagram
    participant Client
    participant Database
    participant IssueRepo
    participant SQLite
    
    Client->>Database: create_issue(depends_on=["1.5"])
    Database->>IssueRepo: create_issue()
    IssueRepo->>SQLite: INSERT INTO issues
    SQLite-->>IssueRepo: issue_id
    IssueRepo->>IssueRepo: resolve "1.5" to issue_id
    IssueRepo->>IssueRepo: _detect_circular_dependency()
    IssueRepo->>SQLite: INSERT INTO issue_dependencies
    SQLite-->>IssueRepo: success
    IssueRepo-->>Database: issue_id
    Database-->>Client: issue_id
    
    Client->>Database: get_issue(issue_id)
    Database->>IssueRepo: get_issue()
    IssueRepo->>SQLite: SELECT FROM issues
    SQLite-->>IssueRepo: issue_row
    IssueRepo->>SQLite: SELECT FROM issue_dependencies
    SQLite-->>IssueRepo: dependency_rows
    IssueRepo->>IssueRepo: _row_to_issue() + populate depends_on
    IssueRepo-->>Database: Issue object
    Database-->>Client: Issue with dependencies

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has a TODO comment in `file:codeframe/persistence/repositories/issue_repository.py` at line 169 that returns an empty array for issue dependencies. The Issue dataclass in `file:codeframe/core/models.py` does not have a `depends_on` field. However, the system already implements a similar pattern for task dependencies using a junction table (`task_dependencies`) with supporting methods. The schema manager in `file:codeframe/persistence/schema_manager.py` creates all database tables but lacks an `issue_dependencies` table. The implementation should follow the existing task dependency pattern for consistency.

This feature is marked as "Future" priority, indicating it is an optimization for complex project planning that is not required for the current workflow (Steps 1-10). The implementation should be designed for eventual integration without blocking current development.

## Approach

The implementation will follow the established task dependency pattern by creating an `issue_dependencies` junction table, adding a `depends_on` field to the Issue model, implementing CRUD methods in the issue repository, and updating the schema manager. Dependencies will be stored as issue numbers (strings like "1.5", "2.1") rather than IDs for better usability, matching the GitHub issue specification. The solution will include circular dependency detection, proper indexing for performance, and comprehensive test coverage following the existing test patterns in `file:tests/persistence/test_database_issues.py`. This implementation is designed as a self-contained feature that can be integrated when prioritized without impacting current workflows.

## Implementation Steps

### 1. Update Issue Model

**File**: `file:codeframe/core/models.py`

Add a `depends_on` field to the `Issue` dataclass (after line 195):
- Add `depends_on: List[str] = field(default_factory=list)` to store issue numbers this issue depends on
- Update the `to_dict()` method to include the `depends_on` field in serialization
- This field will be populated from the `issue_dependencies` junction table when issues are loaded

### 2. Create Issue Dependencies Table

**File**: `file:codeframe/persistence/schema_manager.py`

In the `_create_issue_task_tables()` method (after the task_dependencies table creation at line 309):
- Add SQL to create `issue_dependencies` table with columns: `id`, `issue_id`, `depends_on_issue_id`, `dependency_type`, `created_at`
- Include UNIQUE constraint on `(issue_id, depends_on_issue_id, dependency_type)` to prevent duplicates
- Add foreign key constraints referencing `issues(id)` with CASCADE delete on both foreign keys

In the `_create_indexes()` method (after the task_dependencies indexes at line 747):
- Create index on `issue_dependencies(issue_id)` for fast lookup of dependencies
- Create index on `issue_dependencies(depends_on_issue_id)` for reverse dependency queries

### 3. Implement Issue Dependency Methods

**File**: `file:codeframe/persistence/repositories/issue_repository.py`

Add new methods following the task dependency pattern from `file:codeframe/persistence/repositories/task_repository.py`:

**Method: `add_issue_dependency(issue_id: int, depends_on_issue_id: int, dependency_type: str = 'blocks') -> None`**
- Validate both issue IDs exist in the database
- Check for circular dependencies by traversing the dependency graph using `_detect_circular_dependency()`
- Raise `ValueError` if circular dependency would be created
- Insert into `issue_dependencies` junction table with the specified dependency_type
- Commit transaction

**Method: `get_issue_dependencies(issue_id: int) -> List[str]`**
- Query `issue_dependencies` table for the given issue_id
- Join with `issues` table to get issue_numbers
- Return list of issue numbers (strings) that this issue depends on
- Return empty list if issue has no dependencies

**Method: `get_dependent_issues(issue_id: int) -> List[str]`**
- Query `issue_dependencies` table where `depends_on_issue_id` matches
- Join with `issues` table to get issue_numbers
- Return list of issue numbers that depend on this issue
- Return empty list if no issues depend on this one

**Method: `remove_issue_dependency(issue_id: int, depends_on_issue_id: int) -> int`**
- Delete from `issue_dependencies` junction table
- Commit transaction
- Return number of rows deleted

**Method: `clear_all_issue_dependencies(issue_id: int) -> int`**
- Delete all rows from `issue_dependencies` where `issue_id` matches
- Commit transaction
- Return number of rows deleted

**Method: `_detect_circular_dependency(issue_id: int, depends_on_issue_id: int) -> bool`**
- Implement depth-first search to detect cycles in the dependency graph
- Return True if adding this dependency would create a cycle
- Return False if dependency is safe to add
- Used by `add_issue_dependency()` for validation before insertion

### 4. Update Issue Creation and Retrieval

**File**: `file:codeframe/persistence/repositories/issue_repository.py`

**Update `create_issue()` method** (around line 40):
- After inserting the issue and obtaining the issue_id, check if the Issue object has `depends_on` field populated
- For each dependency issue number in the `depends_on` list, resolve to issue_id and call `add_issue_dependency()`
- Handle case where dependency issue numbers don't exist by logging a warning (non-blocking for MVP)
- Alternatively, raise `ValueError` if strict validation is preferred

**Update `_row_to_issue()` method** (around line 340):
- After creating the Issue object from the row, call `get_issue_dependencies(issue_id)` to fetch dependencies
- Set the `depends_on` field with the returned list of issue numbers
- Return the populated Issue object with dependencies loaded

**Update `get_issues_with_tasks()` method** (around line 159):
- Replace the TODO comment at line 159 with actual dependency parsing
- Call `get_issue_dependencies(issue_dict["id"])` to get the list of dependency issue numbers
- Assign to `"depends_on"` key in the formatted issue dictionary

### 5. Add Database Delegation Methods

**File**: `file:codeframe/persistence/database.py`

Add delegation methods to the Database class (following the pattern around line 388):
- `add_issue_dependency(issue_id: int, depends_on_issue_id: int, dependency_type: str = 'blocks') -> None` - delegates to `self.issues.add_issue_dependency()`
- `get_issue_dependencies(issue_id: int) -> List[str]` - delegates to `self.issues.get_issue_dependencies()`
- `get_dependent_issues(issue_id: int) -> List[str]` - delegates to `self.issues.get_dependent_issues()`
- `remove_issue_dependency(issue_id: int, depends_on_issue_id: int) -> int` - delegates to `self.issues.remove_issue_dependency()`
- `clear_all_issue_dependencies(issue_id: int) -> int` - delegates to `self.issues.clear_all_issue_dependencies()`

These methods provide a clean public API for dependency management while keeping the implementation in the repository layer.

### 6. Update Allowed Fields Whitelist

**File**: `file:codeframe/persistence/repositories/issue_repository.py`

Update `ALLOWED_ISSUE_FIELDS` set (around line 23):
- Add `"depends_on"` to the whitelist to allow updating dependencies via `update_issue()`
- Note: The `depends_on` field in the whitelist refers to the JSON-stored field; actual dependency management should use the dedicated `add_issue_dependency()` and `remove_issue_dependency()` methods

### 7. Write Comprehensive Tests

**File**: `file:tests/persistence/test_database_issues.py`

Add new test class `TestIssueDependencies` following the pattern of existing test classes:

**Test: `test_add_issue_dependency()`**
- Create two issues in the same project
- Add dependency relationship using `add_issue_dependency()`
- Verify junction table entry exists
- Verify `get_issue_dependencies()` returns correct issue number

**Test: `test_get_issue_dependencies_empty()`**
- Create issue with no dependencies
- Verify `get_issue_dependencies()` returns empty list

**Test: `test_get_dependent_issues()`**
- Create issue A that depends on issue B
- Verify `get_dependent_issues(B)` returns [A]
- Verify `get_dependent_issues(A)` returns empty list

**Test: `test_remove_issue_dependency()`**
- Add dependency, then remove it using `remove_issue_dependency()`
- Verify junction table entry is deleted
- Verify `get_issue_dependencies()` returns empty list

**Test: `test_clear_all_issue_dependencies()`**
- Add multiple dependencies to one issue
- Clear all using `clear_all_issue_dependencies()`
- Verify all removed

**Test: `test_circular_dependency_detection()`**
- Create issues A, B, C
- Add A→B, B→C
- Attempt to add C→A (should fail with ValueError)
- Verify error is raised and not inserted

**Test: `test_create_issue_with_dependencies()`**
- Create issue with `depends_on=["1.5", "1.8"]` in constructor
- Verify dependencies are stored correctly in junction table
- Load issue and verify `depends_on` field is populated

**Test: `test_load_issue_with_dependencies()`**
- Create issue with dependencies
- Load via `get_issue()`
- Verify `depends_on` field is populated with correct issue numbers

**Test: `test_dependency_types()`**
- Add dependencies with different types (blocks, related, parent-child)
- Verify all types are stored and retrieved correctly
- Verify UNIQUE constraint prevents duplicate (issue_id, depends_on_issue_id, dependency_type)

**Test: `test_issue_dependencies_cascade_delete()`**
- Create dependency relationship
- Delete parent issue using `delete_all_project_issues()`
- Verify junction table entries are deleted (CASCADE)

**Test: `test_nonexistent_dependency_issue()`**
- Attempt to create issue depending on non-existent issue number
- Verify appropriate error handling (ValueError or warning)

### 8. Update API Response Format

**File**: `file:codeframe/persistence/repositories/issue_repository.py`

Verify the `get_issues_with_tasks()` method (line 159) now returns populated `depends_on` arrays instead of empty arrays after implementing step 4. The API response should include the `depends_on` field with actual issue numbers instead of the current empty array placeholder.

## Database Migration Considerations

Since this adds a new table, existing databases will need migration:
- The `issue_dependencies` table will be created automatically via `CREATE TABLE IF NOT EXISTS` in `_create_issue_task_tables()`
- No data migration needed as this is a new feature
- Existing issues will have empty dependency lists by default
- The schema manager's idempotent design ensures safe application to existing databases

## Visual Architecture

```mermaid
graph TD
    A[Issue Model] -->|has field| B[depends_on: List str]
    C[issues table] -->|1:N| D[issue_dependencies table]
    D -->|N:1| C
    E[IssueRepository] -->|manages| D
    E -->|CRUD operations| F[add_issue_dependency]
    E -->|CRUD operations| G[get_issue_dependencies]
    E -->|CRUD operations| H[remove_issue_dependency]
    E -->|validation| I[_detect_circular_dependency]
    J[Database class] -->|delegates to| E
    K[API /issues endpoint] -->|calls| J
    L[Tests] -->|verify| E
    L -->|verify| I
```

## Dependency Flow

```mermaid
sequenceDiagram
    participant Client
    participant Database
    participant IssueRepo
    participant SQLite
    
    Client->>Database: create_issue(depends_on=["1.5"])
    Database->>IssueRepo: create_issue()
    IssueRepo->>SQLite: INSERT INTO issues
    SQLite-->>IssueRepo: issue_id
    IssueRepo->>IssueRepo: resolve "1.5" to issue_id
    IssueRepo->>IssueRepo: _detect_circular_dependency()
    IssueRepo->>SQLite: INSERT INTO issue_dependencies
    SQLite-->>IssueRepo: success
    IssueRepo-->>Database: issue_id
    Database-->>Client: issue_id
    
    Client->>Database: get_issue(issue_id)
    Database->>IssueRepo: get_issue()
    IssueRepo->>SQLite: SELECT FROM issues
    SQLite-->>IssueRepo: issue_row
    IssueRepo->>SQLite: SELECT FROM issue_dependencies
    SQLite-->>IssueRepo: dependency_rows
    IssueRepo->>IssueRepo: _row_to_issue() + populate depends_on
    IssueRepo-->>Database: Issue object
    Database-->>Client: Issue with dependencies
```

---

Execution Information

Branch: main
Commit: 2e66ed3

---

💡 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

---

🔗 Related PRs

#216 - feat(db): implement P0 database TODOs - issue deps & audit logging [merged]

---

🧪 Issue enrichment is currently in open beta.

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

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!

[traycerai]

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

New Plan

Observations

The codebase currently has a TODO comment in file:codeframe/persistence/repositories/issue_repository.py at line 169 that returns an empty array for issue dependencies. The Issue dataclass in file:codeframe/core/models.py does not have a depends_on field. However, the system already implements a similar pattern for task dependencies using a junction table (task_dependencies) with supporting methods. The schema manager in file:codeframe/persistence/schema_manager.py creates all database tables but lacks an issue_dependencies table. The implementation should follow the existing task dependency pattern for consistency.

Approach

The implementation will follow the established task dependency pattern by creating an issue_dependencies junction table, adding a depends_on field to the Issue model, implementing CRUD methods in the issue repository, and updating the schema manager. Dependencies will be stored as issue numbers (strings like "1.5", "2.1") rather than IDs for better usability, matching the GitHub issue specification. The solution will include circular dependency detection, proper indexing for performance, and comprehensive test coverage following the existing test patterns in file:tests/persistence/test_database_issues.py.

Implementation Steps

1. Update Issue Model

File: file:codeframe/core/models.py

Add a depends_on field to the Issue dataclass (around line 195):

• Add depends_on: List[str] = field(default_factory=list) to store issue numbers this issue depends on
• Update the to_dict() method to include the depends_on field in serialization

2. Create Issue Dependencies Table

File: file:codeframe/persistence/schema_manager.py

In the _create_issue_task_tables() method (after line 200):

• Add SQL to create issue_dependencies table with columns: id, issue_id, depends_on_issue_id, dependency_type, created_at
• Include UNIQUE constraint on (issue_id, depends_on_issue_id, dependency_type) to prevent duplicates
• Add foreign key constraints referencing issues(id) with CASCADE delete

In the _create_indexes() method (after line 611):

• Create index on issue_dependencies(issue_id) for fast lookup of dependencies
• Create index on issue_dependencies(depends_on_issue_id) for reverse dependency queries

3. Implement Issue Dependency Methods

File: file:codeframe/persistence/repositories/issue_repository.py

Add new methods following the task dependency pattern from file:codeframe/persistence/repositories/task_repository.py:

Method: add_issue_dependency(issue_id: int, depends_on_issue_id: int, dependency_type: str = 'blocks')

• Validate both issue IDs exist
• Check for circular dependencies by traversing the dependency graph
• Insert into issue_dependencies junction table
• Commit transaction

Method: get_issue_dependencies(issue_id: int) -> List[str]

• Query issue_dependencies table for the given issue_id
• Join with issues table to get issue_numbers
• Return list of issue numbers (strings) that this issue depends on

Method: get_dependent_issues(issue_id: int) -> List[str]

• Query issue_dependencies table where depends_on_issue_id matches
• Join with issues table to get issue_numbers
• Return list of issue numbers that depend on this issue

Method: remove_issue_dependency(issue_id: int, depends_on_issue_id: int)

• Delete from issue_dependencies junction table
• Commit transaction

Method: clear_all_issue_dependencies(issue_id: int)

• Delete all rows from issue_dependencies where issue_id matches
• Commit transaction

Method: _detect_circular_dependency(issue_id: int, depends_on_issue_id: int) -> bool

• Implement depth-first search to detect cycles in the dependency graph
• Return True if adding this dependency would create a cycle
• Used by add_issue_dependency() for validation

4. Update Issue Creation and Retrieval

File: file:codeframe/persistence/repositories/issue_repository.py

Update create_issue() method (around line 39):

• After inserting the issue, check if the Issue object has depends_on field populated
• For each dependency issue number, resolve to issue_id and call add_issue_dependency()
• Handle case where dependency issue numbers don't exist (log warning or raise error)

Update _row_to_issue() method (around line 309):

• After creating the Issue object, call get_issue_dependencies(issue_id) to fetch dependencies
• Set the depends_on field with the returned list of issue numbers
• Return the populated Issue object

Update get_issues_with_tasks() method (around line 126):

• Replace the TODO comment at line 165 with actual dependency parsing
• Call get_issue_dependencies(issue_dict["id"]) to get the list
• Assign to "depends_on" key in the formatted issue dictionary

5. Add Database Delegation Methods

File: file:codeframe/persistence/database.py

Add delegation methods to the Database class (following the pattern around line 388):

• add_issue_dependency() - delegates to self.issues.add_issue_dependency()
• get_issue_dependencies() - delegates to self.issues.get_issue_dependencies()
• get_dependent_issues() - delegates to self.issues.get_dependent_issues()
• remove_issue_dependency() - delegates to self.issues.remove_issue_dependency()
• clear_all_issue_dependencies() - delegates to self.issues.clear_all_issue_dependencies()

6. Update Allowed Fields Whitelist

File: file:codeframe/persistence/repositories/issue_repository.py

Update ALLOWED_ISSUE_FIELDS set (around line 23):

• Add "depends_on" to the whitelist to allow updating dependencies via update_issue()

7. Write Comprehensive Tests

File: file:tests/persistence/test_database_issues.py

Add new test class TestIssueDependencies following the pattern of existing test classes:

Test: test_add_issue_dependency()

• Create two issues
• Add dependency relationship
• Verify junction table entry exists
• Verify get_issue_dependencies() returns correct issue number

Test: test_get_issue_dependencies_empty()

• Create issue with no dependencies
• Verify returns empty list

Test: test_get_dependent_issues()

• Create issue A that depends on issue B
• Verify get_dependent_issues(B) returns [A]

Test: test_remove_issue_dependency()

• Add dependency, then remove it
• Verify junction table entry is deleted

Test: test_clear_all_issue_dependencies()

• Add multiple dependencies
• Clear all
• Verify all removed

Test: test_circular_dependency_detection()

• Create issues A, B, C
• Add A→B, B→C
• Attempt to add C→A (should fail)
• Verify error is raised

Test: test_create_issue_with_dependencies()

• Create issue with depends_on=["1.5", "1.8"]
• Verify dependencies are stored correctly

Test: test_load_issue_with_dependencies()

• Create issue with dependencies
• Load via get_issue()
• Verify depends_on field is populated

Test: test_dependency_types()

• Add dependencies with different types (blocks, related, parent-child)
• Verify all types are stored and retrieved correctly

Test: test_issue_dependencies_cascade_delete()

• Create dependency relationship
• Delete parent issue
• Verify junction table entries are deleted (CASCADE)

Test: test_nonexistent_dependency_issue()

• Attempt to create issue depending on non-existent issue number
• Verify appropriate error handling

8. Update API Response Format

File: file:codeframe/persistence/repositories/issue_repository.py

Verify the get_issues_with_tasks() method (line 165) now returns populated depends_on arrays instead of empty arrays after implementing step 4.

Database Migration Considerations

Since this adds a new table, existing databases will need migration:

• The issue_dependencies table will be created automatically via CREATE TABLE IF NOT EXISTS
• No data migration needed as this is a new feature
• Existing issues will have empty dependency lists by default

Visual Architecture

graph TD
    A[Issue Model] -->|has field| B[depends_on: List str]
    C[issues table] -->|1:N| D[issue_dependencies table]
    D -->|N:1| C
    E[IssueRepository] -->|manages| D
    E -->|CRUD operations| F[add_issue_dependency]
    E -->|CRUD operations| G[get_issue_dependencies]
    E -->|CRUD operations| H[remove_issue_dependency]
    E -->|validation| I[_detect_circular_dependency]
    J[Database class] -->|delegates to| E
    K[API /issues endpoint] -->|calls| J
    L[Tests] -->|verify| E
    L -->|verify| I

Loading

Dependency Flow

sequenceDiagram
    participant Client
    participant Database
    participant IssueRepo
    participant SQLite
    
    Client->>Database: create_issue(depends_on=["1.5"])
    Database->>IssueRepo: create_issue()
    IssueRepo->>SQLite: INSERT INTO issues
    SQLite-->>IssueRepo: issue_id
    IssueRepo->>IssueRepo: resolve "1.5" to issue_id
    IssueRepo->>IssueRepo: _detect_circular_dependency()
    IssueRepo->>SQLite: INSERT INTO issue_dependencies
    SQLite-->>IssueRepo: success
    IssueRepo-->>Database: issue_id
    Database-->>Client: issue_id
    
    Client->>Database: get_issue(issue_id)
    Database->>IssueRepo: get_issue()
    IssueRepo->>SQLite: SELECT FROM issues
    SQLite-->>IssueRepo: issue_row
    IssueRepo->>SQLite: SELECT FROM issue_dependencies
    SQLite-->>IssueRepo: dependency_rows
    IssueRepo->>IssueRepo: _row_to_issue() + populate depends_on
    IssueRepo-->>Database: Issue object
    Database-->>Client: Issue with dependencies

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has a TODO comment in `file:codeframe/persistence/repositories/issue_repository.py` at line 169 that returns an empty array for issue dependencies. The Issue dataclass in `file:codeframe/core/models.py` does not have a `depends_on` field. However, the system already implements a similar pattern for task dependencies using a junction table (`task_dependencies`) with supporting methods. The schema manager in `file:codeframe/persistence/schema_manager.py` creates all database tables but lacks an `issue_dependencies` table. The implementation should follow the existing task dependency pattern for consistency.

## Approach

The implementation will follow the established task dependency pattern by creating an `issue_dependencies` junction table, adding a `depends_on` field to the Issue model, implementing CRUD methods in the issue repository, and updating the schema manager. Dependencies will be stored as issue numbers (strings like "1.5", "2.1") rather than IDs for better usability, matching the GitHub issue specification. The solution will include circular dependency detection, proper indexing for performance, and comprehensive test coverage following the existing test patterns in `file:tests/persistence/test_database_issues.py`.

## Implementation Steps

### 1. Update Issue Model

**File**: `file:codeframe/core/models.py`

Add a `depends_on` field to the `Issue` dataclass (around line 195):
- Add `depends_on: List[str] = field(default_factory=list)` to store issue numbers this issue depends on
- Update the `to_dict()` method to include the `depends_on` field in serialization

### 2. Create Issue Dependencies Table

**File**: `file:codeframe/persistence/schema_manager.py`

In the `_create_issue_task_tables()` method (after line 200):
- Add SQL to create `issue_dependencies` table with columns: `id`, `issue_id`, `depends_on_issue_id`, `dependency_type`, `created_at`
- Include UNIQUE constraint on `(issue_id, depends_on_issue_id, dependency_type)` to prevent duplicates
- Add foreign key constraints referencing `issues(id)` with CASCADE delete

In the `_create_indexes()` method (after line 611):
- Create index on `issue_dependencies(issue_id)` for fast lookup of dependencies
- Create index on `issue_dependencies(depends_on_issue_id)` for reverse dependency queries

### 3. Implement Issue Dependency Methods

**File**: `file:codeframe/persistence/repositories/issue_repository.py`

Add new methods following the task dependency pattern from `file:codeframe/persistence/repositories/task_repository.py`:

**Method: `add_issue_dependency(issue_id: int, depends_on_issue_id: int, dependency_type: str = 'blocks')`**
- Validate both issue IDs exist
- Check for circular dependencies by traversing the dependency graph
- Insert into `issue_dependencies` junction table
- Commit transaction

**Method: `get_issue_dependencies(issue_id: int) -> List[str]`**
- Query `issue_dependencies` table for the given issue_id
- Join with `issues` table to get issue_numbers
- Return list of issue numbers (strings) that this issue depends on

**Method: `get_dependent_issues(issue_id: int) -> List[str]`**
- Query `issue_dependencies` table where `depends_on_issue_id` matches
- Join with `issues` table to get issue_numbers
- Return list of issue numbers that depend on this issue

**Method: `remove_issue_dependency(issue_id: int, depends_on_issue_id: int)`**
- Delete from `issue_dependencies` junction table
- Commit transaction

**Method: `clear_all_issue_dependencies(issue_id: int)`**
- Delete all rows from `issue_dependencies` where `issue_id` matches
- Commit transaction

**Method: `_detect_circular_dependency(issue_id: int, depends_on_issue_id: int) -> bool`**
- Implement depth-first search to detect cycles in the dependency graph
- Return True if adding this dependency would create a cycle
- Used by `add_issue_dependency()` for validation

### 4. Update Issue Creation and Retrieval

**File**: `file:codeframe/persistence/repositories/issue_repository.py`

**Update `create_issue()` method** (around line 39):
- After inserting the issue, check if the Issue object has `depends_on` field populated
- For each dependency issue number, resolve to issue_id and call `add_issue_dependency()`
- Handle case where dependency issue numbers don't exist (log warning or raise error)

**Update `_row_to_issue()` method** (around line 309):
- After creating the Issue object, call `get_issue_dependencies(issue_id)` to fetch dependencies
- Set the `depends_on` field with the returned list of issue numbers
- Return the populated Issue object

**Update `get_issues_with_tasks()` method** (around line 126):
- Replace the TODO comment at line 165 with actual dependency parsing
- Call `get_issue_dependencies(issue_dict["id"])` to get the list
- Assign to `"depends_on"` key in the formatted issue dictionary

### 5. Add Database Delegation Methods

**File**: `file:codeframe/persistence/database.py`

Add delegation methods to the Database class (following the pattern around line 388):
- `add_issue_dependency()` - delegates to `self.issues.add_issue_dependency()`
- `get_issue_dependencies()` - delegates to `self.issues.get_issue_dependencies()`
- `get_dependent_issues()` - delegates to `self.issues.get_dependent_issues()`
- `remove_issue_dependency()` - delegates to `self.issues.remove_issue_dependency()`
- `clear_all_issue_dependencies()` - delegates to `self.issues.clear_all_issue_dependencies()`

### 6. Update Allowed Fields Whitelist

**File**: `file:codeframe/persistence/repositories/issue_repository.py`

Update `ALLOWED_ISSUE_FIELDS` set (around line 23):
- Add `"depends_on"` to the whitelist to allow updating dependencies via `update_issue()`

### 7. Write Comprehensive Tests

**File**: `file:tests/persistence/test_database_issues.py`

Add new test class `TestIssueDependencies` following the pattern of existing test classes:

**Test: `test_add_issue_dependency()`**
- Create two issues
- Add dependency relationship
- Verify junction table entry exists
- Verify `get_issue_dependencies()` returns correct issue number

**Test: `test_get_issue_dependencies_empty()`**
- Create issue with no dependencies
- Verify returns empty list

**Test: `test_get_dependent_issues()`**
- Create issue A that depends on issue B
- Verify `get_dependent_issues(B)` returns [A]

**Test: `test_remove_issue_dependency()`**
- Add dependency, then remove it
- Verify junction table entry is deleted

**Test: `test_clear_all_issue_dependencies()`**
- Add multiple dependencies
- Clear all
- Verify all removed

**Test: `test_circular_dependency_detection()`**
- Create issues A, B, C
- Add A→B, B→C
- Attempt to add C→A (should fail)
- Verify error is raised

**Test: `test_create_issue_with_dependencies()`**
- Create issue with `depends_on=["1.5", "1.8"]`
- Verify dependencies are stored correctly

**Test: `test_load_issue_with_dependencies()`**
- Create issue with dependencies
- Load via `get_issue()`
- Verify `depends_on` field is populated

**Test: `test_dependency_types()`**
- Add dependencies with different types (blocks, related, parent-child)
- Verify all types are stored and retrieved correctly

**Test: `test_issue_dependencies_cascade_delete()`**
- Create dependency relationship
- Delete parent issue
- Verify junction table entries are deleted (CASCADE)

**Test: `test_nonexistent_dependency_issue()`**
- Attempt to create issue depending on non-existent issue number
- Verify appropriate error handling

### 8. Update API Response Format

**File**: `file:codeframe/persistence/repositories/issue_repository.py`

Verify the `get_issues_with_tasks()` method (line 165) now returns populated `depends_on` arrays instead of empty arrays after implementing step 4.

## Database Migration Considerations

Since this adds a new table, existing databases will need migration:
- The `issue_dependencies` table will be created automatically via `CREATE TABLE IF NOT EXISTS`
- No data migration needed as this is a new feature
- Existing issues will have empty dependency lists by default

## Visual Architecture

```mermaid
graph TD
    A[Issue Model] -->|has field| B[depends_on: List str]
    C[issues table] -->|1:N| D[issue_dependencies table]
    D -->|N:1| C
    E[IssueRepository] -->|manages| D
    E -->|CRUD operations| F[add_issue_dependency]
    E -->|CRUD operations| G[get_issue_dependencies]
    E -->|CRUD operations| H[remove_issue_dependency]
    E -->|validation| I[_detect_circular_dependency]
    J[Database class] -->|delegates to| E
    K[API /issues endpoint] -->|calls| J
    L[Tests] -->|verify| E
    L -->|verify| I
```

## Dependency Flow

```mermaid
sequenceDiagram
    participant Client
    participant Database
    participant IssueRepo
    participant SQLite
    
    Client->>Database: create_issue(depends_on=["1.5"])
    Database->>IssueRepo: create_issue()
    IssueRepo->>SQLite: INSERT INTO issues
    SQLite-->>IssueRepo: issue_id
    IssueRepo->>IssueRepo: resolve "1.5" to issue_id
    IssueRepo->>IssueRepo: _detect_circular_dependency()
    IssueRepo->>SQLite: INSERT INTO issue_dependencies
    SQLite-->>IssueRepo: success
    IssueRepo-->>Database: issue_id
    Database-->>Client: issue_id
    
    Client->>Database: get_issue(issue_id)
    Database->>IssueRepo: get_issue()
    IssueRepo->>SQLite: SELECT FROM issues
    SQLite-->>IssueRepo: issue_row
    IssueRepo->>SQLite: SELECT FROM issue_dependencies
    SQLite-->>IssueRepo: dependency_rows
    IssueRepo->>IssueRepo: _row_to_issue() + populate depends_on
    IssueRepo-->>Database: Issue object
    Database-->>Client: Issue with dependencies
```

---

Execution Information

Branch: main
Commit: 52e78e0

[frankbria]

Re-labeled from P3 to Future. Issue dependencies are stored but parsing from database is an optimization. Current workflow doesn't require this for Steps 1-10.