[Phase 4] Reconciliation: GitHub Issue State Sync

[frankbria]

Summary

Extend the reconciliation engine to check GitHub issue state for tasks that are linked to GitHub issues, and adjust batch execution accordingly.

Parent issue: #403

Scope

Changes to core/reconciler.py

1. Add GitHubReconciler that extends the base reconciler:

   • For tasks with a linked GitHub issue (via cf pr or task metadata)
   • Fetch current issue state from GitHub API
   • Map GitHub states to CodeFrame actions:
     • Issue closed → recommend SKIP (task no longer needed)
     • Issue open with new comments → recommend logging (context update)
     • PR merged → recommend SKIP (work already done)
     • PR closed (not merged) → recommend FAIL

2. GitHub API integration:

   • Use existing codeframe/git/github_integration.py module
   • Rate-limit aware (don't exceed GitHub API limits during reconciliation)
   • Cache issue state for check_interval_ms to avoid repeated API calls

3. Configuration:

   • reconcile_github: true/false (default: true if GitHub remote detected)
   • Requires GITHUB_TOKEN in environment

Changes to core/reconciler.py (base)

4. Add ReconcilerRegistry to chain multiple reconcilers:
   • Local state reconciler (from [Phase 4] Reconciliation: State Checker Engine #404)
   • GitHub reconciler (this issue)
   • Future: other tracker reconcilers

Acceptance Criteria

• GitHub issue state fetched for linked tasks during reconciliation
• Closed GitHub issues → tasks skipped in batch
• Merged PRs → tasks marked done
• API calls rate-limited and cached
• Works without GitHub token (gracefully disabled)
• Integration test with mocked GitHub API responses

Dependencies

• Depends on [Phase 4] Reconciliation: State Checker Engine #404 (reconciliation engine)
• Uses existing codeframe/git/github_integration.py

[traycerai]

Plan

Observations

No core/reconciler.py file exists yet — this is a fully net-new module. The codebase has two parallel task systems: the legacy Task in codeframe/core/models.py (with issue_id/task_number fields, no GitHub issue link) and the v2 Task in codeframe/core/tasks.py (no GitHub link fields either). The pull_requests table in codeframe/persistence/schema_manager.py stores pr_number/pr_url linked to issue_id. GitHubIntegration in codeframe/git/github_integration.py only has PR methods — no issue-state fetch. GlobalConfig already holds github_token and github_repo. The existing rate-limiter in codeframe/lib/rate_limiter.py uses slowapi (HTTP middleware), not suitable for internal API call throttling.

Approach

Create codeframe/core/reconciler.py with a BaseReconciler + ReconcilerRegistry + GitHubReconciler hierarchy. Since tasks lack a native GitHub issue link, reconciliation will look up linked PRs from the pull_requests table via issue_id. Issue-state fetching requires a new get_issue method on GitHubIntegration. A simple timestamp-based in-memory cache (dict of {key: (result, fetched_at)}) avoids adding a new dependency while satisfying the check_interval_ms requirement.

---

Implementation Steps

1. Add get_issue to GitHubIntegration

File: file:codeframe/git/github_integration.py

Add a new @dataclass IssueDetails with fields: number, url, state, title, body, created_at, comments (count), pull_request (optional bool to indicate if it's a PR cross-reference).

Add async def get_issue(self, issue_number: int) -> IssueDetails that calls GET /repos/{owner}/{repo}/issues/{issue_number} via _make_request, then parses and returns an IssueDetails. The GitHub Issues API returns both issues and PRs; include merged_at detection via the pull_request.merged_at field if present in the response.

---

2. Create codeframe/core/reconciler.py

This is the core deliverable. Structure it as follows:

2a. Enums and data structures

• ReconcilerAction enum: SKIP, FAIL, LOG_CONTEXT, PROCEED — represents what the reconciler recommends for a given task.
• ReconciliationResult dataclass: task_id: str, action: ReconcilerAction, reason: str, metadata: dict — returned per task by each reconciler.
• ReconcilerConfig dataclass: reconcile_github: bool (default True if GITHUB_TOKEN env var is set), check_interval_ms: int (default 60_000), github_token: Optional[str], github_repo: Optional[str]. Populate defaults by reading from get_global_config() in codeframe/core/config.py.

2b. BaseReconciler abstract class

class BaseReconciler:
    async def reconcile_task(self, task_id: str, ...) -> ReconciliationResult
    async def reconcile_batch(self, task_ids: list[str], ...) -> dict[str, ReconciliationResult]

reconcile_batch iterates task_ids, calls reconcile_task for each, and collects results. Both methods are async.

2c. GitHubReconciler(BaseReconciler)

Constructor: Accepts ReconcilerConfig and optionally a pre-built GitHubIntegration instance (for testability). Initialise an in-memory cache: _cache: dict[str, tuple[IssueDetails | PRDetails, datetime]].

Cache helper _get_cached_or_fetch(key, fetch_coroutine): Check if key is in _cache and (now - fetched_at).total_seconds() * 1000 < check_interval_ms. If fresh, return cached value; otherwise call fetch_coroutine, store result with current timestamp, return it.

_find_linked_github_resource(task_id): Look up the task's issue_id from the workspace DB, then query pull_requests table for any PR linked to that issue_id with a non-null pr_number. Return (pr_number, resource_type) where resource_type is "pr" or "issue".

The task_id here refers to the v2 Task.id (UUID). For the legacy Task with issue_id, the reconciler resolves the pull_requests record via issue_id. Both lookup paths converge on a pr_number stored in the DB.

reconcile_task(task_id, workspace):

1. Call _find_linked_github_resource(task_id) — if nothing found, return ReconciliationResult(action=PROCEED, reason="No linked GitHub resource").
2. Build the cache key (f"pr:{pr_number}" or f"issue:{number}").
3. Fetch from cache or GitHub API (using GitHubIntegration.get_pull_request for PRs, get_issue for issues) via _get_cached_or_fetch.
4. Apply mapping rules:

GitHub State	Type	ReconcilerAction
closed, merged_at is set	PR	SKIP
closed, no merged_at	PR	FAIL
closed	Issue	SKIP
open, comments > 0	Issue	LOG_CONTEXT
open	PR or Issue	PROCEED

5. On GitHubAPIError with status 401/403: log a warning, return PROCEED (graceful degradation — token missing or invalid).
6. On GitHubAPIError with status 404: return PROCEED (resource not found — don't block).
7. On any other exception: log error, return PROCEED (fail open).

Rate limiting: Before each API call (outside of cache hit), enforce a minimum inter-call delay using a _last_api_call_at timestamp. GitHub's primary rate limit is 5000 req/hr; enforce a conservative floor of 1 request per 100ms using asyncio.sleep if the elapsed time since _last_api_call_at is less than 100ms.

2d. ReconcilerRegistry

class ReconcilerRegistry:
    def __init__(self, reconcilers: list[BaseReconciler])
    async def reconcile_batch(self, task_ids, workspace) -> dict[str, ReconciliationResult]

Iterate reconcilers in order. For each task, if any reconciler returns SKIP or FAIL, stop checking further reconcilers for that task (short-circuit). Merge results: the most severe action wins. Order of severity: FAIL > SKIP > LOG_CONTEXT > PROCEED.

2e. Factory function

def create_default_registry(config: Optional[ReconcilerConfig] = None) -> ReconcilerRegistry:

• Read config from get_global_config() if not provided.
• If reconcile_github is True and GITHUB_TOKEN is available, add a GitHubReconciler; otherwise skip it silently.
• Return a ReconcilerRegistry with the assembled reconcilers.

---

3. Wire reconciliation into batch execution

File: file:codeframe/core/conductor.py

In start_batch(), before the main execution loop (the _execute_serial / _execute_parallel call), add an optional reconciliation pre-pass:

1. Create a ReconcilerRegistry via create_default_registry().
2. Call await registry.reconcile_batch(task_ids, workspace) to get results: dict[str, ReconciliationResult].
3. Filter task_ids: remove tasks where action == SKIP (log a notice), mark tasks where action == FAIL with TaskStatus.FAILED in the DB immediately using tasks.update_status().
4. For LOG_CONTEXT tasks, append the reconciler's reason to the task's description or log it — this surfaces new GitHub comments for context.
5. Proceed with the filtered list of tasks for actual execution.

Since conductor.py runs synchronously in a thread pool, run the async reconciliation via asyncio.run(registry.reconcile_batch(...)) at the pre-pass step (the pattern is already used in pr_commands.py with asyncio.run).

---

4. Add reconcile_github to GlobalConfig and EnvironmentConfig

File: file:codeframe/core/config.py

• Add reconcile_github: bool = Field(True, alias="RECONCILE_GITHUB") to GlobalConfig. Default True — the factory function in reconciler.py will still disable it at runtime when GITHUB_TOKEN is absent.
• Update ReconcilerConfig.reconcile_github default logic to read this flag.

---

5. Architecture diagram

sequenceDiagram
    participant Conductor as conductor.start_batch()
    participant Registry as ReconcilerRegistry
    participant GHReconciler as GitHubReconciler
    participant Cache as In-memory Cache
    participant GHApi as GitHubIntegration
    participant DB as pull_requests table

    Conductor->>Registry: reconcile_batch(task_ids, workspace)
    loop for each task_id
        Registry->>GHReconciler: reconcile_task(task_id, workspace)
        GHReconciler->>DB: lookup pr_number via issue_id
        alt no linked resource
            GHReconciler-->>Registry: PROCEED
        else resource found
            GHReconciler->>Cache: check cache (check_interval_ms)
            alt cache hit
                Cache-->>GHReconciler: cached state
            else cache miss
                GHReconciler->>GHApi: get_pull_request / get_issue
                GHApi-->>GHReconciler: PRDetails / IssueDetails
                GHReconciler->>Cache: store with timestamp
            end
            GHReconciler->>GHReconciler: map state → ReconcilerAction
            GHReconciler-->>Registry: ReconciliationResult
        end
    end
    Registry-->>Conductor: dict[task_id, ReconciliationResult]
    Conductor->>Conductor: filter SKIP tasks, fail FAIL tasks
    Conductor->>Conductor: execute remaining tasks

Loading

---

6. Graceful no-token behaviour

In GitHubReconciler.__init__, attempt to create the GitHubIntegration client. If ValueError is raised (no token or no repo), set self._enabled = False. In reconcile_task, if _enabled is False, immediately return ReconciliationResult(action=PROCEED, reason="GitHub reconciliation disabled (no token)"). This ensures the reconciler is safe to instantiate and call even without credentials.

Import In IDE

🤖 Prompt for AI Agents

## Observations

No `core/reconciler.py` file exists yet — this is a fully net-new module. The codebase has two parallel task systems: the legacy `Task` in `codeframe/core/models.py` (with `issue_id`/`task_number` fields, no GitHub issue link) and the v2 `Task` in `codeframe/core/tasks.py` (no GitHub link fields either). The `pull_requests` table in `codeframe/persistence/schema_manager.py` stores `pr_number`/`pr_url` linked to `issue_id`. `GitHubIntegration` in `codeframe/git/github_integration.py` only has PR methods — no issue-state fetch. `GlobalConfig` already holds `github_token` and `github_repo`. The existing rate-limiter in `codeframe/lib/rate_limiter.py` uses `slowapi` (HTTP middleware), not suitable for internal API call throttling.

## Approach

Create `codeframe/core/reconciler.py` with a `BaseReconciler` + `ReconcilerRegistry` + `GitHubReconciler` hierarchy. Since tasks lack a native GitHub issue link, reconciliation will look up linked PRs from the `pull_requests` table via `issue_id`. Issue-state fetching requires a new `get_issue` method on `GitHubIntegration`. A simple timestamp-based in-memory cache (dict of `{key: (result, fetched_at)}`) avoids adding a new dependency while satisfying the `check_interval_ms` requirement.

---

## Implementation Steps

### 1. Add `get_issue` to `GitHubIntegration`

**File:** `file:codeframe/git/github_integration.py`

Add a new `@dataclass IssueDetails` with fields: `number`, `url`, `state`, `title`, `body`, `created_at`, `comments` (count), `pull_request` (optional bool to indicate if it's a PR cross-reference).

Add `async def get_issue(self, issue_number: int) -> IssueDetails` that calls `GET /repos/{owner}/{repo}/issues/{issue_number}` via `_make_request`, then parses and returns an `IssueDetails`. The GitHub Issues API returns both issues and PRs; include `merged_at` detection via the `pull_request.merged_at` field if present in the response.

---

### 2. Create `codeframe/core/reconciler.py`

This is the core deliverable. Structure it as follows:

#### 2a. Enums and data structures

- `ReconcilerAction` enum: `SKIP`, `FAIL`, `LOG_CONTEXT`, `PROCEED` — represents what the reconciler recommends for a given task.
- `ReconciliationResult` dataclass: `task_id: str`, `action: ReconcilerAction`, `reason: str`, `metadata: dict` — returned per task by each reconciler.
- `ReconcilerConfig` dataclass: `reconcile_github: bool` (default `True` if `GITHUB_TOKEN` env var is set), `check_interval_ms: int` (default `60_000`), `github_token: Optional[str]`, `github_repo: Optional[str]`. Populate defaults by reading from `get_global_config()` in `codeframe/core/config.py`.

#### 2b. `BaseReconciler` abstract class

```
class BaseReconciler:
    async def reconcile_task(self, task_id: str, ...) -> ReconciliationResult
    async def reconcile_batch(self, task_ids: list[str], ...) -> dict[str, ReconciliationResult]
```

`reconcile_batch` iterates `task_ids`, calls `reconcile_task` for each, and collects results. Both methods are `async`.

#### 2c. `GitHubReconciler(BaseReconciler)`

**Constructor:** Accepts `ReconcilerConfig` and optionally a pre-built `GitHubIntegration` instance (for testability). Initialise an in-memory cache: `_cache: dict[str, tuple[IssueDetails | PRDetails, datetime]]`.

**Cache helper** `_get_cached_or_fetch(key, fetch_coroutine)`: Check if `key` is in `_cache` and `(now - fetched_at).total_seconds() * 1000 < check_interval_ms`. If fresh, return cached value; otherwise call `fetch_coroutine`, store result with current timestamp, return it.

**`_find_linked_github_resource(task_id)`**: Look up the task's `issue_id` from the workspace DB, then query `pull_requests` table for any PR linked to that `issue_id` with a non-null `pr_number`. Return `(pr_number, resource_type)` where `resource_type` is `"pr"` or `"issue"`.

> The `task_id` here refers to the v2 `Task.id` (UUID). For the legacy `Task` with `issue_id`, the reconciler resolves the `pull_requests` record via `issue_id`. Both lookup paths converge on a `pr_number` stored in the DB.

**`reconcile_task(task_id, workspace)`**:
1. Call `_find_linked_github_resource(task_id)` — if nothing found, return `ReconciliationResult(action=PROCEED, reason="No linked GitHub resource")`.
2. Build the cache key (`f"pr:{pr_number}"` or `f"issue:{number}"`).
3. Fetch from cache or GitHub API (using `GitHubIntegration.get_pull_request` for PRs, `get_issue` for issues) via `_get_cached_or_fetch`.
4. Apply mapping rules:

| GitHub State | Type | `ReconcilerAction` |
|---|---|---|
| `closed`, `merged_at` is set | PR | `SKIP` |
| `closed`, no `merged_at` | PR | `FAIL` |
| `closed` | Issue | `SKIP` |
| `open`, `comments > 0` | Issue | `LOG_CONTEXT` |
| `open` | PR or Issue | `PROCEED` |

5. On `GitHubAPIError` with status 401/403: log a warning, return `PROCEED` (graceful degradation — token missing or invalid).
6. On `GitHubAPIError` with status 404: return `PROCEED` (resource not found — don't block).
7. On any other exception: log error, return `PROCEED` (fail open).

**Rate limiting**: Before each API call (outside of cache hit), enforce a minimum inter-call delay using a `_last_api_call_at` timestamp. GitHub's primary rate limit is 5000 req/hr; enforce a conservative floor of 1 request per 100ms using `asyncio.sleep` if the elapsed time since `_last_api_call_at` is less than 100ms.

#### 2d. `ReconcilerRegistry`

```
class ReconcilerRegistry:
    def __init__(self, reconcilers: list[BaseReconciler])
    async def reconcile_batch(self, task_ids, workspace) -> dict[str, ReconciliationResult]
```

Iterate reconcilers in order. For each task, if any reconciler returns `SKIP` or `FAIL`, stop checking further reconcilers for that task (short-circuit). Merge results: the most severe action wins. Order of severity: `FAIL > SKIP > LOG_CONTEXT > PROCEED`.

#### 2e. Factory function

`def create_default_registry(config: Optional[ReconcilerConfig] = None) -> ReconcilerRegistry`:  
- Read config from `get_global_config()` if not provided.  
- If `reconcile_github` is `True` and `GITHUB_TOKEN` is available, add a `GitHubReconciler`; otherwise skip it silently.  
- Return a `ReconcilerRegistry` with the assembled reconcilers.

---

### 3. Wire reconciliation into batch execution

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

In `start_batch()`, before the main execution loop (the `_execute_serial` / `_execute_parallel` call), add an optional reconciliation pre-pass:

1. Create a `ReconcilerRegistry` via `create_default_registry()`.
2. Call `await registry.reconcile_batch(task_ids, workspace)` to get `results: dict[str, ReconciliationResult]`.
3. Filter `task_ids`: remove tasks where `action == SKIP` (log a notice), mark tasks where `action == FAIL` with `TaskStatus.FAILED` in the DB immediately using `tasks.update_status()`.
4. For `LOG_CONTEXT` tasks, append the reconciler's `reason` to the task's description or log it — this surfaces new GitHub comments for context.
5. Proceed with the filtered list of tasks for actual execution.

Since `conductor.py` runs synchronously in a thread pool, run the async reconciliation via `asyncio.run(registry.reconcile_batch(...))` at the pre-pass step (the pattern is already used in `pr_commands.py` with `asyncio.run`).

---

### 4. Add `reconcile_github` to `GlobalConfig` and `EnvironmentConfig`

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

- Add `reconcile_github: bool = Field(True, alias="RECONCILE_GITHUB")` to `GlobalConfig`. Default `True` — the factory function in `reconciler.py` will still disable it at runtime when `GITHUB_TOKEN` is absent.
- Update `ReconcilerConfig.reconcile_github` default logic to read this flag.

---

### 5. Architecture diagram

```mermaid
sequenceDiagram
    participant Conductor as conductor.start_batch()
    participant Registry as ReconcilerRegistry
    participant GHReconciler as GitHubReconciler
    participant Cache as In-memory Cache
    participant GHApi as GitHubIntegration
    participant DB as pull_requests table

    Conductor->>Registry: reconcile_batch(task_ids, workspace)
    loop for each task_id
        Registry->>GHReconciler: reconcile_task(task_id, workspace)
        GHReconciler->>DB: lookup pr_number via issue_id
        alt no linked resource
            GHReconciler-->>Registry: PROCEED
        else resource found
            GHReconciler->>Cache: check cache (check_interval_ms)
            alt cache hit
                Cache-->>GHReconciler: cached state
            else cache miss
                GHReconciler->>GHApi: get_pull_request / get_issue
                GHApi-->>GHReconciler: PRDetails / IssueDetails
                GHReconciler->>Cache: store with timestamp
            end
            GHReconciler->>GHReconciler: map state → ReconcilerAction
            GHReconciler-->>Registry: ReconciliationResult
        end
    end
    Registry-->>Conductor: dict[task_id, ReconciliationResult]
    Conductor->>Conductor: filter SKIP tasks, fail FAIL tasks
    Conductor->>Conductor: execute remaining tasks
```

---

### 6. Graceful no-token behaviour

In `GitHubReconciler.__init__`, attempt to create the `GitHubIntegration` client. If `ValueError` is raised (no token or no repo), set `self._enabled = False`. In `reconcile_task`, if `_enabled` is `False`, immediately return `ReconciliationResult(action=PROCEED, reason="GitHub reconciliation disabled (no token)")`. This ensures the reconciler is safe to instantiate and call even without credentials.

---

Execution Information

Branch: main
Commit: 705b160

---

💡 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]

🔗 Related PRs

#35 - fix: Resolve E2E test timeout failures in GitHub Actions [merged]
#205 - feat(planning): Add planning phase automation and task approval [merged]
#229 - feat(e2e): add state reconciliation tests for late-joining users [merged]
#234 - fix(ui): make TaskStats phase-aware to fix late-joining user bug [merged]
#363 - feat: wire ReactAgent into runtime with --engine react CLI flag [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 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!

[frankbria]

Implemented in PR #439 (merged). All reconciliation components (engine, conductor integration, GitHub sync) delivered as a single PR implementing parent issue #403.