[Phase 4] Implement Goal Recitation for Long-Running Tasks

[frankbria]

Summary

Implement periodic goal recitation to prevent agent drift during long-running tasks with many tool calls.

Background: State of the Art

From Philipp Schmid's 5 Practical Tips for Context Engineering:

"Recite Goals to not get lost: Prevent the model from 'getting lost' by having it periodically restate its objectives. This keeps the primary goal in its recent attention span."

Key data point: "A typical task in Manus requires around 50 tool calls on average."

With 50+ tool calls, the original task description may have scrolled far out of the model's attention window. Combined with accumulated tool outputs (error messages, file contents, test results), the model can:

• Forget the original objective
• Optimize for intermediate goals (e.g., fixing a test) instead of the actual task
• Enter repetitive loops without progress toward completion

Goal recitation is a forcing function: periodically inject "Reminder: Your current objective is X. Progress so far: Y. Remaining: Z."

Current State in CodeFRAME

The Lead Agent decomposes PRD → tasks and assigns to workers. Questions:

1. Task visibility: Do workers have the original task description in every context window?
2. Progress tracking: Do workers know what they've accomplished vs. what remains?
3. Drift detection: Is there any mechanism to detect when a worker is "off track"?
4. Long tasks: For tasks requiring 20+ tool calls, is goal visibility maintained?

The explicit planning pillar (PRD decomposition) is a form of goal structure, but per-call goal injection may not be implemented.

Investigation Tasks

1. Audit goal visibility in context

   • For a long-running task, examine what goal/task information is in context at call N vs. call N+20
   • Check if original task description is still visible or scrolled out
   • Measure context position of goal info (beginning? middle? end?)

2. Identify drift patterns

   • Review logs for tasks that took unusually long
   • Look for patterns: repeated similar tool calls, circular behavior, abandoning original objective
   • Check if workers sometimes complete "something" that isn't what was asked

3. Design goal recitation mechanism

   Option A: Periodic injection

   • Every N tool calls (e.g., 10), inject goal reminder
   • Include: original objective, progress summary, remaining steps

   Option B: Context position guarantee

   • Always place goal summary in final 500 tokens (recent attention)
   • Update summary after each step

   Option C: Self-recitation prompt

   • Before each tool call, agent states: "I am doing X because Y toward goal Z"
   • Explicit chain-of-thought linking action to objective

4. Integrate with existing planning

   • The Lead Agent's task decomposition could provide "checkpoints"
   • At each checkpoint, force goal recitation
   • Workers could have a "recite goal" tool they must call periodically

Success Criteria

• Documented goal visibility patterns in current implementation
• Identified any drift patterns in historical task logs
• Implemented goal recitation mechanism
• Measured reduction in drift/circular behavior
• Task completion rate improvement for long tasks (20+ tool calls)

Implementation Sketch

class GoalRecitationMiddleware:
    def __init__(self, recite_every_n_calls: int = 10):
        self.call_count = 0
        self.recite_interval = recite_every_n_calls
    
    def wrap_context(self, context: Context, task: Task) -> Context:
        self.call_count += 1
        
        if self.call_count % self.recite_interval == 0:
            recitation = f"""
            === GOAL RECITATION ===
            Original Objective: {task.description}
            Completed Steps: {task.completed_steps}
            Remaining: {task.remaining_steps}
            Current Focus: {task.current_subtask}
            ========================
            """
            context.append_to_end(recitation)
        
        return context

References

• Context Engineering Tips - Philipp Schmid
• Agents 2.0: Deep Agents - Pillar 1: Explicit Planning
• Manus architecture insights (50 tool calls per task baseline)

[traycerai]

Plan

Observations

The codebase has a sophisticated multi-agent architecture with context management (HOT/WARM/COLD tiers), task decomposition, and SDK-based tool execution. However, there's no mechanism for goal recitation during long-running tasks. Agents receive tasks via execute_task(task: Task) with static system prompts built at creation time. The context manager handles token limits and flash saves, but doesn't track tool call counts or inject periodic goal reminders. The SDK hooks (file:codeframe/lib/sdk_hooks.py) provide pre/post tool execution points but aren't used for goal recitation.

---

Approach

Implement a three-layer goal recitation system that prevents agent drift: (1) Tool Call Tracking - add a counter to track tool calls per task execution, (2) Goal Recitation Middleware - inject goal reminders every N tool calls via SDK post-tool hooks, and (3) Context Integration - store goal state as HOT-tier context items. This approach leverages existing SDK hooks and context management without requiring major architectural changes. The recitation will include original task objective, completed steps (inferred from tool outputs), and current focus, positioned at the end of context for maximum attention.

---

Implementation Steps

1. Audit Current Goal Visibility

Objective: Document how task information flows through agent execution and identify where goal visibility is lost.

Tasks:

• Trace task execution flow from LeadAgent._assign_and_execute_task() through HybridWorkerAgent.execute_task() (file:codeframe/agents/hybrid_worker.py, lines 123-205)
• Examine how HybridWorkerAgent._build_execution_prompt() (lines 207-259) constructs prompts with context
• Review system prompt construction in BackendWorkerAgent and similar worker types
• Document what task information is available at tool call N vs N+20 by examining SDK conversation history
• Measure context position of task description in typical execution scenarios

Deliverables:

• Document: docs/goal-visibility-audit.md with findings on context degradation patterns
• Identify specific tool call thresholds where task description scrolls out of attention window

---

2. Design Goal Recitation Data Model

Objective: Extend data models to support goal tracking and recitation state with database persistence.

Tasks:

• Add GOAL_RECITATION to ContextItemType enum in file:codeframe/core/models.py (line 434) alongside existing TASK, CODE, ERROR, TEST_RESULT, PRD_SECTION
• Create GoalRecitationState Pydantic model in file:codeframe/core/models.py:
  • Fields: task_id: int, tool_call_count: int, last_recitation_at: datetime, completed_actions: List[str], remaining_actions: List[str], current_focus: str, drift_score: float
  • Add validation: tool_call_count >= 0, drift_score between 0.0-1.0
• Add recitation_interval configuration field to agent definitions (default: 10 tool calls, configurable per agent type)
• Extend Task model with optional goal_summary: str field for concise objective statement (max 200 chars)
• Create database table goal_recitation_states with columns: id, task_id, agent_id, tool_call_count, last_recitation_at, drift_score, created_at

Deliverables:

• Updated file:codeframe/core/models.py with new Pydantic models and enum value
• Database migration script: codeframe/persistence/migrations/migration_00X_add_goal_recitation.py with table creation and indexes
• Schema documentation in migration file

---

3. Implement Tool Call Counter

Objective: Track tool calls per task execution to trigger recitation at intervals and detect circular patterns.

Tasks:

• Create ToolCallTracker class in new file codeframe/lib/tool_call_tracker.py:
  • Methods: increment(task_id), get_count(task_id), reset(task_id), should_recite(task_id, interval), get_recent_tools(task_id, n=5)
  • Store counts in memory (dict) with task_id as key for fast access
  • Persist counts to database via GoalRecitationState for session resume capability
  • Track recent tool calls (last 5-10) to enable circular behavior detection
• Integrate tracker into SDK post-tool hook in file:codeframe/lib/sdk_hooks.py:
  • Modify create_metrics_post_hook() signature to accept tool_call_tracker and goal_recitation_middleware parameters
  • Increment counter after each tool execution (in post-tool hook)
  • Check should_recite() and trigger recitation if interval reached
  • Return flag indicating if recitation was triggered
• Add tracker instance to HybridWorkerAgent.__init__() and pass to SDK hooks during execute_task()
• Ensure tracker is reset at task start and persisted at task end

Deliverables:

• New file: codeframe/lib/tool_call_tracker.py with ToolCallTracker class
• Updated file:codeframe/lib/sdk_hooks.py with counter integration in create_metrics_post_hook()
• Unit tests: tests/lib/test_tool_call_tracker.py covering increment, reset, recitation triggers

---

4. Build Goal Recitation Middleware

Objective: Create middleware that injects goal reminders into agent context at intervals with drift awareness.

Tasks:

• Create GoalRecitationMiddleware class in new file codeframe/lib/goal_recitation.py:
  • Method: build_recitation(task: Task, tool_call_count: int, recent_actions: List[str], drift_score: float = 0.0) -> str
  • Format recitation as structured text with sections: "Original Objective", "Progress So Far", "Remaining Steps", "Current Focus"
  • If drift_score > 0.5, prepend warning: "⚠️ ATTENTION: You may be drifting from the original objective. Refocus on: {task.description}"
  • Keep recitation concise (< 500 tokens) to minimize context overhead
  • Include tool call count and recitation number for transparency
• Integrate with SDK hooks:
  • Modify create_metrics_post_hook() to accept goal_recitation_middleware parameter
  • Check if recitation should trigger via tool_call_tracker.should_recite()
  • If yes, call GoalRecitationMiddleware.build_recitation() with drift score
  • Inject recitation as a system message via SDK conversation history
• Store recitation as HOT-tier context item via save_context_item():
  • Use item_type=ContextItemType.GOAL_RECITATION
  • Set importance_score=0.95 to ensure HOT tier placement
  • Include metadata: tool_call_count, drift_score, recitation_number

Deliverables:

• New file: codeframe/lib/goal_recitation.py with GoalRecitationMiddleware class
• Updated file:codeframe/lib/sdk_hooks.py with recitation injection in post-tool hook
• Unit tests: tests/lib/test_goal_recitation.py covering formatting, drift warnings, token limits

---

5. Implement Progress Tracking

Objective: Track completed actions and remaining steps to populate recitation content with high accuracy.

Tasks:

• Create ProgressTracker class in file:codeframe/lib/goal_recitation.py:
  • Method: extract_actions_from_tools(tool_outputs: List[Dict]) -> List[str]
  • Parse recent tool outputs (Write, Bash, Read, Glob, Grep) to infer completed actions
  • Example outputs: "Write tool → Created file src/main.py", "Bash tool → Ran tests (3 passed)", "Read tool → Examined file config.yaml"
  • Limit to last 5 actions to keep recitation concise
• Integrate with HybridWorkerAgent.execute_task():
  • After each tool execution, extract action summary via ProgressTracker.extract_actions_from_tools()
  • Store in GoalRecitationState.completed_actions list
  • Update GoalRecitationState.tool_call_count after each tool
• Infer remaining steps from task dependencies:
  • Query task dependencies via database in LeadAgent._assign_and_execute_task()
  • List incomplete dependent tasks as "remaining steps" in recitation
  • Update remaining steps as task progresses

Deliverables:

• ProgressTracker class in file:codeframe/lib/goal_recitation.py with action extraction logic
• Integration with HybridWorkerAgent.execute_task() to track actions per tool call
• Unit tests covering action extraction for all tool types (Write, Bash, Read, Glob, Grep)

---

6. Integrate with Lead Agent Coordination Loop

Objective: Enable goal recitation in the multi-agent execution orchestration with proper state management.

Tasks:

• Modify LeadAgent._assign_and_execute_task() (file:codeframe/agents/lead_agent.py):
  • Initialize GoalRecitationState when assigning task to worker (before calling worker.execute_task())
  • Extract goal_summary from task description (first 200 chars or first sentence)
  • Pass recitation interval configuration to worker agent via task metadata
  • Store initial goal summary in database via GoalRecitationState record
  • Log goal recitation initialization for debugging
• Update HybridWorkerAgent.execute_task() (file:codeframe/agents/hybrid_worker.py, lines 123-205):
  • Initialize ToolCallTracker at task start (before SDK execution)
  • Initialize GoalRecitationMiddleware with task and agent configuration
  • Pass tracker and middleware to SDK hooks via build_codeframe_hooks()
  • Configure recitation interval from agent definition or default to 10 tool calls
  • Reset tracker at task completion
• Ensure recitation state persists across agent pool reuse:
  • When agent marked idle, preserve recitation state in database
  • When agent reused, restore recitation state from database
  • Handle session resume: restore tool_call_count and completed_actions

Deliverables:

• Updated file:codeframe/agents/lead_agent.py with recitation initialization in _assign_and_execute_task()
• Updated file:codeframe/agents/hybrid_worker.py with middleware integration in execute_task()
• Integration tests: tests/agents/test_goal_recitation_integration.py covering end-to-end flow

---

7. Add Configuration and Tuning

Objective: Make goal recitation configurable and tunable per agent type with environment overrides.

Tasks:

• Add configuration to agent definitions (YAML files in codeframe/agents/definitions/):
  • recitation_interval: Number of tool calls between recitations (default: 10, range: 5-50)
  • recitation_enabled: Boolean flag to enable/disable (default: true)
  • recitation_template: Custom template for recitation format (optional, uses default if not provided)
  • drift_detection_enabled: Boolean flag for drift detection (default: true)
  • drift_threshold: Drift score threshold to trigger warning (default: 0.5, range: 0.0-1.0)
• Add environment variables for global override:
  • CODEFRAME_RECITATION_INTERVAL: Override default interval (e.g., "15")
  • CODEFRAME_RECITATION_ENABLED: Global enable/disable (e.g., "true")
  • CODEFRAME_DRIFT_DETECTION_ENABLED: Global drift detection toggle
• Create configuration loader in file:codeframe/lib/goal_recitation.py:
  • Method: load_recitation_config(agent_type: str) -> Dict
  • Load from agent definition YAML file
  • Merge with environment variable overrides
  • Validate configuration values (interval range, threshold range)
  • Return merged config dict with all settings

Deliverables:

• Updated agent definition files (backend-worker.yaml, frontend-worker.yaml, etc.) with recitation configuration
• Configuration loader in file:codeframe/lib/goal_recitation.py with validation
• Documentation: docs/goal-recitation-config.md with examples and tuning guide

---

8. Implement Drift Detection

Objective: Detect when agents are going in circles or off-track and escalate appropriately.

Tasks:

• Create DriftDetector class in file:codeframe/lib/goal_recitation.py:
  • Method: detect_circular_behavior(tool_history: List[Dict]) -> float (returns drift score 0.0-1.0)
  • Check for repeated similar tool calls (e.g., same file written 3+ times in last 10 calls)
  • Check for repeated bash commands (e.g., same test run 3+ times)
  • Return higher drift score for more obvious circular patterns
  • Method: detect_objective_drift(task: Task, recent_actions: List[str]) -> float
  • Calculate keyword overlap between task description and recent actions
  • Use simple keyword matching (extract nouns/verbs from task, check presence in actions)
  • Return drift score: 1.0 if no overlap, 0.0 if high overlap
  • Method: compute_drift_score(circular_score: float, objective_score: float) -> float
  • Weighted average: 0.6 * circular_score + 0.4 * objective_score
• Integrate with recitation middleware:
  • If drift_score > 0.5, inject stronger reminder in recitation: "⚠️ ATTENTION: You may be drifting from the original objective..."
  • If drift_score > 0.7 for 3+ consecutive recitations, escalate to SYNC blocker
  • Store drift events in database for analysis
• Log drift events for analysis:
  • Store in database table drift_events with task_id, timestamp, drift_score, circular_score, objective_score, recent_actions

Deliverables:

• DriftDetector class in file:codeframe/lib/goal_recitation.py with circular and objective drift detection
• Integration with recitation middleware to compute and use drift scores
• SYNC blocker escalation logic in LeadAgent._assign_and_execute_task() when drift persists
• Unit tests: tests/lib/test_drift_detection.py covering circular patterns, objective drift, score computation

---

9. Add Monitoring and Metrics

Objective: Track effectiveness of goal recitation in reducing drift and improving task completion with comprehensive analytics.

Tasks:

• Extend MetricsTracker (file:codeframe/lib/metrics_tracker.py):
  • Add method: record_recitation(task_id: int, tool_call_count: int, recitation_content: str, drift_score: float)
  • Add method: record_task_completion(task_id: int, total_tool_calls: int, recitations_triggered: int, drift_detected: bool, completion_status: str)
  • Store metrics in database table recitation_metrics with columns: id, task_id, agent_id, tool_call_count, drift_score, created_at
  • Store completion metrics in table task_completion_metrics with columns: id, task_id, total_tool_calls, recitations_triggered, drift_detected, completion_status, created_at
• Add dashboard visualization:
  • Create React component: web-ui/src/components/GoalRecitationMetrics.tsx
  • Display: average tool calls per task, recitation frequency, drift detection rate, task completion rate
  • Show before/after comparison: tasks with recitation vs. without (if historical data available)
  • Display drift score distribution and correlation with task completion
• Create analysis script: scripts/analyze-goal-recitation.py:
  • Query metrics from database
  • Compare task completion rates for tasks with/without recitation (target: +10% improvement)
  • Identify optimal recitation intervals per agent type (analyze completion rate vs. interval)
  • Analyze drift score distribution and correlation with task success
  • Generate report: reports/goal-recitation-effectiveness.md with findings and recommendations

Deliverables:

• Updated file:codeframe/lib/metrics_tracker.py with recitation and completion metrics methods
• New component: web-ui/src/components/GoalRecitationMetrics.tsx with dashboard visualizations
• Analysis script: scripts/analyze-goal-recitation.py with comprehensive metrics analysis
• Report template: reports/goal-recitation-effectiveness.md

---

10. Testing and Validation

Objective: Ensure goal recitation works correctly and improves task completion with comprehensive test coverage.

Tasks:

• Unit tests for all new components:
  • tests/lib/test_tool_call_tracker.py - counter logic, reset, recitation triggers, persistence
  • tests/lib/test_goal_recitation.py - recitation building, formatting, token limits, drift warnings
  • tests/lib/test_drift_detection.py - circular behavior detection, objective drift, score computation
• Integration tests:
  • tests/agents/test_goal_recitation_integration.py - end-to-end recitation flow with HybridWorkerAgent
  • Test scenario: task with 50+ tool calls, verify recitation triggers at intervals (every 10 calls)
  • Test scenario: agent drift detection and warning injection
  • Test scenario: SYNC blocker escalation when drift persists for 3+ recitations
  • Test scenario: session resume with recitation state restoration
• Manual testing:
  • Create test task requiring 30+ tool calls (e.g., multi-file refactoring)
  • Monitor recitation injection in agent logs and context items
  • Verify task completion without circular behavior
  • Verify recitation content accuracy (objective, progress, remaining steps)
• Performance testing:
  • Measure context overhead of recitation (should be < 500 tokens per recitation)
  • Verify no significant latency increase per tool call (< 50ms overhead)
  • Measure database query performance for recitation state persistence
  • Benchmark drift detection algorithm (should complete in < 100ms)

Deliverables:

• Complete test suite with >85% coverage for new code (tool_call_tracker, goal_recitation, drift_detection)
• Test report: docs/goal-recitation-test-results.md with test results, coverage metrics, and findings
• Performance benchmarks in test report showing latency and overhead measurements
• Integration test results showing recitation triggers and drift detection accuracy

---

Architecture Diagram

sequenceDiagram
    participant LA as LeadAgent
    participant APM as AgentPoolManager
    participant HW as HybridWorkerAgent
    participant SDK as SDKClientWrapper
    participant Hook as SDK Post-Tool Hook
    participant TCT as ToolCallTracker
    participant GRM as GoalRecitationMiddleware
    participant CM as ContextManager

    LA->>APM: assign_task(task)
    APM->>HW: create/reuse agent
    APM->>TCT: initialize counter for task
    HW->>SDK: execute_task(task)
    
    loop Every Tool Call
        SDK->>Hook: post_tool_hook(tool_output)
        Hook->>TCT: increment(task_id)
        Hook->>TCT: should_recite(task_id, interval=10)?
        
        alt Recitation Interval Reached
            TCT-->>Hook: true
            Hook->>GRM: build_recitation(task, count, actions)
            GRM->>CM: save_context_item(GOAL_RECITATION, content)
            CM-->>GRM: item_id
            GRM-->>Hook: recitation_text
            Hook->>SDK: inject recitation as system message
        else Continue Normal Execution
            TCT-->>Hook: false
        end
        
        Hook-->>SDK: continue
    end
    
    SDK-->>HW: task_result
    HW-->>LA: task_completed

Loading

---

Success Criteria

Metric	Target	Measurement Method
Goal visibility maintained	100% of tasks	Audit logs show task objective in context at every recitation
Recitation overhead	< 500 tokens per recitation	Token counter in GoalRecitationMiddleware
Recitation trigger accuracy	100%	Verify recitations trigger at exact intervals (every N tool calls)
Drift detection accuracy	> 80%	Manual review of flagged vs actual drift cases
Task completion improvement	+10% for tasks >20 tool calls	Compare completion rates before/after implementation
No performance regression	< 50ms latency per tool call	Performance benchmarks in tests
Circular behavior detection	> 85% accuracy	Test with known circular patterns (repeated file writes, test loops)
SYNC blocker escalation	Correct timing	Verify escalation triggers after 3+ high-drift recitations

---

Configuration Example

# codeframe/agents/definitions/backend-worker.yaml
name: "Backend Worker"
type: "backend"
system_prompt: |
  You are a Backend Worker Agent...
recitation_config:
  enabled: true
  interval: 10  # Recite every 10 tool calls
  drift_detection_enabled: true
  drift_threshold: 0.5  # Warn if drift score > 0.5
  template: |
    === GOAL RECITATION (Call #{tool_call_count}) ===
    Original Objective: {task.description}
    Progress: {completed_actions}
    Remaining: {remaining_steps}
    Current Focus: {current_subtask}
    Drift Score: {drift_score}
    ========================

Environment variable overrides:

export CODEFRAME_RECITATION_INTERVAL=15
export CODEFRAME_RECITATION_ENABLED=true
export CODEFRAME_DRIFT_DETECTION_ENABLED=true

---

Files to Create/Modify

New Files

• codeframe/lib/tool_call_tracker.py - Tool call counting and tracking
• codeframe/lib/goal_recitation.py - Recitation middleware, progress tracking, and drift detection
• codeframe/persistence/migrations/migration_00X_add_goal_recitation.py - Database schema for goal recitation state and drift events
• tests/lib/test_tool_call_tracker.py - Unit tests for ToolCallTracker
• tests/lib/test_goal_recitation.py - Unit tests for GoalRecitationMiddleware and ProgressTracker
• tests/lib/test_drift_detection.py - Unit tests for DriftDetector
• tests/agents/test_goal_recitation_integration.py - Integration tests for end-to-end recitation flow
• docs/goal-visibility-audit.md - Audit findings on context degradation patterns
• docs/goal-recitation-config.md - Configuration guide with examples and tuning recommendations
• docs/goal-recitation-test-results.md - Test report with coverage metrics and performance benchmarks
• scripts/analyze-goal-recitation.py - Analysis script for metrics and effectiveness measurement
• web-ui/src/components/GoalRecitationMetrics.tsx - Dashboard component for visualization
• codeframe/persistence/migrations/migration_00X_add_drift_events_table.py - Database schema for drift event logging

Modified Files

• codeframe/core/models.py - Add GoalRecitationState Pydantic model, extend ContextItemType enum with GOAL_RECITATION
• codeframe/lib/sdk_hooks.py - Integrate tool call tracking and recitation injection in create_metrics_post_hook()
• codeframe/agents/lead_agent.py - Initialize recitation state in _assign_and_execute_task(), handle SYNC blocker escalation for drift
• codeframe/agents/hybrid_worker.py - Initialize ToolCallTracker and GoalRecitationMiddleware in execute_task(), pass to SDK hooks
• codeframe/lib/metrics_tracker.py - Add record_recitation() and record_task_completion() methods
• codeframe/agents/definitions/backend-worker.yaml - Add recitation configuration section
• codeframe/agents/definitions/frontend-worker.yaml - Add recitation configuration section
• codeframe/agents/definitions/test-worker.yaml - Add recitation configuration section
• codeframe/agents/definitions/review-worker.yaml - Add recitation configuration section

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a sophisticated multi-agent architecture with context management (HOT/WARM/COLD tiers), task decomposition, and SDK-based tool execution. However, there's **no mechanism for goal recitation** during long-running tasks. Agents receive tasks via `execute_task(task: Task)` with static system prompts built at creation time. The context manager handles token limits and flash saves, but doesn't track tool call counts or inject periodic goal reminders. The SDK hooks (file:codeframe/lib/sdk_hooks.py) provide pre/post tool execution points but aren't used for goal recitation.

---

## Approach

Implement a **three-layer goal recitation system** that prevents agent drift: (1) **Tool Call Tracking** - add a counter to track tool calls per task execution, (2) **Goal Recitation Middleware** - inject goal reminders every N tool calls via SDK post-tool hooks, and (3) **Context Integration** - store goal state as HOT-tier context items. This approach leverages existing SDK hooks and context management without requiring major architectural changes. The recitation will include original task objective, completed steps (inferred from tool outputs), and current focus, positioned at the end of context for maximum attention.

---

## Implementation Steps

### 1. Audit Current Goal Visibility

**Objective:** Document how task information flows through agent execution and identify where goal visibility is lost.

**Tasks:**
- Trace task execution flow from `LeadAgent._assign_and_execute_task()` through `HybridWorkerAgent.execute_task()` (file:codeframe/agents/hybrid_worker.py, lines 123-205)
- Examine how `HybridWorkerAgent._build_execution_prompt()` (lines 207-259) constructs prompts with context
- Review system prompt construction in `BackendWorkerAgent` and similar worker types
- Document what task information is available at tool call N vs N+20 by examining SDK conversation history
- Measure context position of task description in typical execution scenarios

**Deliverables:**
- Document: `docs/goal-visibility-audit.md` with findings on context degradation patterns
- Identify specific tool call thresholds where task description scrolls out of attention window

---

### 2. Design Goal Recitation Data Model

**Objective:** Extend data models to support goal tracking and recitation state with database persistence.

**Tasks:**
- Add `GOAL_RECITATION` to `ContextItemType` enum in file:codeframe/core/models.py (line 434) alongside existing TASK, CODE, ERROR, TEST_RESULT, PRD_SECTION
- Create `GoalRecitationState` Pydantic model in file:codeframe/core/models.py:
  - Fields: `task_id: int`, `tool_call_count: int`, `last_recitation_at: datetime`, `completed_actions: List[str]`, `remaining_actions: List[str]`, `current_focus: str`, `drift_score: float`
  - Add validation: `tool_call_count >= 0`, `drift_score` between 0.0-1.0
- Add `recitation_interval` configuration field to agent definitions (default: 10 tool calls, configurable per agent type)
- Extend `Task` model with optional `goal_summary: str` field for concise objective statement (max 200 chars)
- Create database table `goal_recitation_states` with columns: id, task_id, agent_id, tool_call_count, last_recitation_at, drift_score, created_at

**Deliverables:**
- Updated file:codeframe/core/models.py with new Pydantic models and enum value
- Database migration script: `codeframe/persistence/migrations/migration_00X_add_goal_recitation.py` with table creation and indexes
- Schema documentation in migration file

---

### 3. Implement Tool Call Counter

**Objective:** Track tool calls per task execution to trigger recitation at intervals and detect circular patterns.

**Tasks:**
- Create `ToolCallTracker` class in new file `codeframe/lib/tool_call_tracker.py`:
  - Methods: `increment(task_id)`, `get_count(task_id)`, `reset(task_id)`, `should_recite(task_id, interval)`, `get_recent_tools(task_id, n=5)`
  - Store counts in memory (dict) with task_id as key for fast access
  - Persist counts to database via `GoalRecitationState` for session resume capability
  - Track recent tool calls (last 5-10) to enable circular behavior detection
- Integrate tracker into SDK post-tool hook in file:codeframe/lib/sdk_hooks.py:
  - Modify `create_metrics_post_hook()` signature to accept `tool_call_tracker` and `goal_recitation_middleware` parameters
  - Increment counter after each tool execution (in post-tool hook)
  - Check `should_recite()` and trigger recitation if interval reached
  - Return flag indicating if recitation was triggered
- Add tracker instance to `HybridWorkerAgent.__init__()` and pass to SDK hooks during `execute_task()`
- Ensure tracker is reset at task start and persisted at task end

**Deliverables:**
- New file: `codeframe/lib/tool_call_tracker.py` with ToolCallTracker class
- Updated file:codeframe/lib/sdk_hooks.py with counter integration in `create_metrics_post_hook()`
- Unit tests: `tests/lib/test_tool_call_tracker.py` covering increment, reset, recitation triggers

---

### 4. Build Goal Recitation Middleware

**Objective:** Create middleware that injects goal reminders into agent context at intervals with drift awareness.

**Tasks:**
- Create `GoalRecitationMiddleware` class in new file `codeframe/lib/goal_recitation.py`:
  - Method: `build_recitation(task: Task, tool_call_count: int, recent_actions: List[str], drift_score: float = 0.0) -> str`
  - Format recitation as structured text with sections: "Original Objective", "Progress So Far", "Remaining Steps", "Current Focus"
  - If drift_score > 0.5, prepend warning: "⚠️ ATTENTION: You may be drifting from the original objective. Refocus on: {task.description}"
  - Keep recitation concise (< 500 tokens) to minimize context overhead
  - Include tool call count and recitation number for transparency
- Integrate with SDK hooks:
  - Modify `create_metrics_post_hook()` to accept `goal_recitation_middleware` parameter
  - Check if recitation should trigger via `tool_call_tracker.should_recite()`
  - If yes, call `GoalRecitationMiddleware.build_recitation()` with drift score
  - Inject recitation as a system message via SDK conversation history
- Store recitation as HOT-tier context item via `save_context_item()`:
  - Use `item_type=ContextItemType.GOAL_RECITATION`
  - Set `importance_score=0.95` to ensure HOT tier placement
  - Include metadata: tool_call_count, drift_score, recitation_number

**Deliverables:**
- New file: `codeframe/lib/goal_recitation.py` with GoalRecitationMiddleware class
- Updated file:codeframe/lib/sdk_hooks.py with recitation injection in post-tool hook
- Unit tests: `tests/lib/test_goal_recitation.py` covering formatting, drift warnings, token limits

---

### 5. Implement Progress Tracking

**Objective:** Track completed actions and remaining steps to populate recitation content with high accuracy.

**Tasks:**
- Create `ProgressTracker` class in file:codeframe/lib/goal_recitation.py:
  - Method: `extract_actions_from_tools(tool_outputs: List[Dict]) -> List[str]`
  - Parse recent tool outputs (Write, Bash, Read, Glob, Grep) to infer completed actions
  - Example outputs: "Write tool → Created file src/main.py", "Bash tool → Ran tests (3 passed)", "Read tool → Examined file config.yaml"
  - Limit to last 5 actions to keep recitation concise
- Integrate with `HybridWorkerAgent.execute_task()`:
  - After each tool execution, extract action summary via `ProgressTracker.extract_actions_from_tools()`
  - Store in `GoalRecitationState.completed_actions` list
  - Update `GoalRecitationState.tool_call_count` after each tool
- Infer remaining steps from task dependencies:
  - Query task dependencies via database in `LeadAgent._assign_and_execute_task()`
  - List incomplete dependent tasks as "remaining steps" in recitation
  - Update remaining steps as task progresses

**Deliverables:**
- `ProgressTracker` class in file:codeframe/lib/goal_recitation.py with action extraction logic
- Integration with `HybridWorkerAgent.execute_task()` to track actions per tool call
- Unit tests covering action extraction for all tool types (Write, Bash, Read, Glob, Grep)

---

### 6. Integrate with Lead Agent Coordination Loop

**Objective:** Enable goal recitation in the multi-agent execution orchestration with proper state management.

**Tasks:**
- Modify `LeadAgent._assign_and_execute_task()` (file:codeframe/agents/lead_agent.py):
  - Initialize `GoalRecitationState` when assigning task to worker (before calling `worker.execute_task()`)
  - Extract `goal_summary` from task description (first 200 chars or first sentence)
  - Pass recitation interval configuration to worker agent via task metadata
  - Store initial goal summary in database via `GoalRecitationState` record
  - Log goal recitation initialization for debugging
- Update `HybridWorkerAgent.execute_task()` (file:codeframe/agents/hybrid_worker.py, lines 123-205):
  - Initialize `ToolCallTracker` at task start (before SDK execution)
  - Initialize `GoalRecitationMiddleware` with task and agent configuration
  - Pass tracker and middleware to SDK hooks via `build_codeframe_hooks()`
  - Configure recitation interval from agent definition or default to 10 tool calls
  - Reset tracker at task completion
- Ensure recitation state persists across agent pool reuse:
  - When agent marked idle, preserve recitation state in database
  - When agent reused, restore recitation state from database
  - Handle session resume: restore tool_call_count and completed_actions

**Deliverables:**
- Updated file:codeframe/agents/lead_agent.py with recitation initialization in `_assign_and_execute_task()`
- Updated file:codeframe/agents/hybrid_worker.py with middleware integration in `execute_task()`
- Integration tests: `tests/agents/test_goal_recitation_integration.py` covering end-to-end flow

---

### 7. Add Configuration and Tuning

**Objective:** Make goal recitation configurable and tunable per agent type with environment overrides.

**Tasks:**
- Add configuration to agent definitions (YAML files in `codeframe/agents/definitions/`):
  - `recitation_interval`: Number of tool calls between recitations (default: 10, range: 5-50)
  - `recitation_enabled`: Boolean flag to enable/disable (default: true)
  - `recitation_template`: Custom template for recitation format (optional, uses default if not provided)
  - `drift_detection_enabled`: Boolean flag for drift detection (default: true)
  - `drift_threshold`: Drift score threshold to trigger warning (default: 0.5, range: 0.0-1.0)
- Add environment variables for global override:
  - `CODEFRAME_RECITATION_INTERVAL`: Override default interval (e.g., "15")
  - `CODEFRAME_RECITATION_ENABLED`: Global enable/disable (e.g., "true")
  - `CODEFRAME_DRIFT_DETECTION_ENABLED`: Global drift detection toggle
- Create configuration loader in file:codeframe/lib/goal_recitation.py:
  - Method: `load_recitation_config(agent_type: str) -> Dict`
  - Load from agent definition YAML file
  - Merge with environment variable overrides
  - Validate configuration values (interval range, threshold range)
  - Return merged config dict with all settings

**Deliverables:**
- Updated agent definition files (backend-worker.yaml, frontend-worker.yaml, etc.) with recitation configuration
- Configuration loader in file:codeframe/lib/goal_recitation.py with validation
- Documentation: `docs/goal-recitation-config.md` with examples and tuning guide

---

### 8. Implement Drift Detection

**Objective:** Detect when agents are going in circles or off-track and escalate appropriately.

**Tasks:**
- Create `DriftDetector` class in file:codeframe/lib/goal_recitation.py:
  - Method: `detect_circular_behavior(tool_history: List[Dict]) -> float` (returns drift score 0.0-1.0)
  - Check for repeated similar tool calls (e.g., same file written 3+ times in last 10 calls)
  - Check for repeated bash commands (e.g., same test run 3+ times)
  - Return higher drift score for more obvious circular patterns
  - Method: `detect_objective_drift(task: Task, recent_actions: List[str]) -> float`
  - Calculate keyword overlap between task description and recent actions
  - Use simple keyword matching (extract nouns/verbs from task, check presence in actions)
  - Return drift score: 1.0 if no overlap, 0.0 if high overlap
  - Method: `compute_drift_score(circular_score: float, objective_score: float) -> float`
  - Weighted average: 0.6 * circular_score + 0.4 * objective_score
- Integrate with recitation middleware:
  - If drift_score > 0.5, inject stronger reminder in recitation: "⚠️ ATTENTION: You may be drifting from the original objective..."
  - If drift_score > 0.7 for 3+ consecutive recitations, escalate to SYNC blocker
  - Store drift events in database for analysis
- Log drift events for analysis:
  - Store in database table `drift_events` with task_id, timestamp, drift_score, circular_score, objective_score, recent_actions

**Deliverables:**
- `DriftDetector` class in file:codeframe/lib/goal_recitation.py with circular and objective drift detection
- Integration with recitation middleware to compute and use drift scores
- SYNC blocker escalation logic in `LeadAgent._assign_and_execute_task()` when drift persists
- Unit tests: `tests/lib/test_drift_detection.py` covering circular patterns, objective drift, score computation

---

### 9. Add Monitoring and Metrics

**Objective:** Track effectiveness of goal recitation in reducing drift and improving task completion with comprehensive analytics.

**Tasks:**
- Extend `MetricsTracker` (file:codeframe/lib/metrics_tracker.py):
  - Add method: `record_recitation(task_id: int, tool_call_count: int, recitation_content: str, drift_score: float)`
  - Add method: `record_task_completion(task_id: int, total_tool_calls: int, recitations_triggered: int, drift_detected: bool, completion_status: str)`
  - Store metrics in database table `recitation_metrics` with columns: id, task_id, agent_id, tool_call_count, drift_score, created_at
  - Store completion metrics in table `task_completion_metrics` with columns: id, task_id, total_tool_calls, recitations_triggered, drift_detected, completion_status, created_at
- Add dashboard visualization:
  - Create React component: `web-ui/src/components/GoalRecitationMetrics.tsx`
  - Display: average tool calls per task, recitation frequency, drift detection rate, task completion rate
  - Show before/after comparison: tasks with recitation vs. without (if historical data available)
  - Display drift score distribution and correlation with task completion
- Create analysis script: `scripts/analyze-goal-recitation.py`:
  - Query metrics from database
  - Compare task completion rates for tasks with/without recitation (target: +10% improvement)
  - Identify optimal recitation intervals per agent type (analyze completion rate vs. interval)
  - Analyze drift score distribution and correlation with task success
  - Generate report: `reports/goal-recitation-effectiveness.md` with findings and recommendations

**Deliverables:**
- Updated file:codeframe/lib/metrics_tracker.py with recitation and completion metrics methods
- New component: `web-ui/src/components/GoalRecitationMetrics.tsx` with dashboard visualizations
- Analysis script: `scripts/analyze-goal-recitation.py` with comprehensive metrics analysis
- Report template: `reports/goal-recitation-effectiveness.md`

---

### 10. Testing and Validation

**Objective:** Ensure goal recitation works correctly and improves task completion with comprehensive test coverage.

**Tasks:**
- Unit tests for all new components:
  - `tests/lib/test_tool_call_tracker.py` - counter logic, reset, recitation triggers, persistence
  - `tests/lib/test_goal_recitation.py` - recitation building, formatting, token limits, drift warnings
  - `tests/lib/test_drift_detection.py` - circular behavior detection, objective drift, score computation
- Integration tests:
  - `tests/agents/test_goal_recitation_integration.py` - end-to-end recitation flow with HybridWorkerAgent
  - Test scenario: task with 50+ tool calls, verify recitation triggers at intervals (every 10 calls)
  - Test scenario: agent drift detection and warning injection
  - Test scenario: SYNC blocker escalation when drift persists for 3+ recitations
  - Test scenario: session resume with recitation state restoration
- Manual testing:
  - Create test task requiring 30+ tool calls (e.g., multi-file refactoring)
  - Monitor recitation injection in agent logs and context items
  - Verify task completion without circular behavior
  - Verify recitation content accuracy (objective, progress, remaining steps)
- Performance testing:
  - Measure context overhead of recitation (should be < 500 tokens per recitation)
  - Verify no significant latency increase per tool call (< 50ms overhead)
  - Measure database query performance for recitation state persistence
  - Benchmark drift detection algorithm (should complete in < 100ms)

**Deliverables:**
- Complete test suite with >85% coverage for new code (tool_call_tracker, goal_recitation, drift_detection)
- Test report: `docs/goal-recitation-test-results.md` with test results, coverage metrics, and findings
- Performance benchmarks in test report showing latency and overhead measurements
- Integration test results showing recitation triggers and drift detection accuracy

---

## Architecture Diagram

```mermaid
sequenceDiagram
    participant LA as LeadAgent
    participant APM as AgentPoolManager
    participant HW as HybridWorkerAgent
    participant SDK as SDKClientWrapper
    participant Hook as SDK Post-Tool Hook
    participant TCT as ToolCallTracker
    participant GRM as GoalRecitationMiddleware
    participant CM as ContextManager

    LA->>APM: assign_task(task)
    APM->>HW: create/reuse agent
    APM->>TCT: initialize counter for task
    HW->>SDK: execute_task(task)
    
    loop Every Tool Call
        SDK->>Hook: post_tool_hook(tool_output)
        Hook->>TCT: increment(task_id)
        Hook->>TCT: should_recite(task_id, interval=10)?
        
        alt Recitation Interval Reached
            TCT-->>Hook: true
            Hook->>GRM: build_recitation(task, count, actions)
            GRM->>CM: save_context_item(GOAL_RECITATION, content)
            CM-->>GRM: item_id
            GRM-->>Hook: recitation_text
            Hook->>SDK: inject recitation as system message
        else Continue Normal Execution
            TCT-->>Hook: false
        end
        
        Hook-->>SDK: continue
    end
    
    SDK-->>HW: task_result
    HW-->>LA: task_completed
```

---

## Success Criteria

| Metric | Target | Measurement Method |
|--------|--------|-------------------|
| Goal visibility maintained | 100% of tasks | Audit logs show task objective in context at every recitation |
| Recitation overhead | < 500 tokens per recitation | Token counter in `GoalRecitationMiddleware` |
| Recitation trigger accuracy | 100% | Verify recitations trigger at exact intervals (every N tool calls) |
| Drift detection accuracy | > 80% | Manual review of flagged vs actual drift cases |
| Task completion improvement | +10% for tasks >20 tool calls | Compare completion rates before/after implementation |
| No performance regression | < 50ms latency per tool call | Performance benchmarks in tests |
| Circular behavior detection | > 85% accuracy | Test with known circular patterns (repeated file writes, test loops) |
| SYNC blocker escalation | Correct timing | Verify escalation triggers after 3+ high-drift recitations |

---

## Configuration Example

```yaml
# codeframe/agents/definitions/backend-worker.yaml
name: "Backend Worker"
type: "backend"
system_prompt: |
  You are a Backend Worker Agent...
recitation_config:
  enabled: true
  interval: 10  # Recite every 10 tool calls
  drift_detection_enabled: true
  drift_threshold: 0.5  # Warn if drift score > 0.5
  template: |
    === GOAL RECITATION (Call #{tool_call_count}) ===
    Original Objective: {task.description}
    Progress: {completed_actions}
    Remaining: {remaining_steps}
    Current Focus: {current_subtask}
    Drift Score: {drift_score}
    ========================
```

Environment variable overrides:
```bash
export CODEFRAME_RECITATION_INTERVAL=15
export CODEFRAME_RECITATION_ENABLED=true
export CODEFRAME_DRIFT_DETECTION_ENABLED=true
```

---

## Files to Create/Modify

### New Files
- `codeframe/lib/tool_call_tracker.py` - Tool call counting and tracking
- `codeframe/lib/goal_recitation.py` - Recitation middleware, progress tracking, and drift detection
- `codeframe/persistence/migrations/migration_00X_add_goal_recitation.py` - Database schema for goal recitation state and drift events
- `tests/lib/test_tool_call_tracker.py` - Unit tests for ToolCallTracker
- `tests/lib/test_goal_recitation.py` - Unit tests for GoalRecitationMiddleware and ProgressTracker
- `tests/lib/test_drift_detection.py` - Unit tests for DriftDetector
- `tests/agents/test_goal_recitation_integration.py` - Integration tests for end-to-end recitation flow
- `docs/goal-visibility-audit.md` - Audit findings on context degradation patterns
- `docs/goal-recitation-config.md` - Configuration guide with examples and tuning recommendations
- `docs/goal-recitation-test-results.md` - Test report with coverage metrics and performance benchmarks
- `scripts/analyze-goal-recitation.py` - Analysis script for metrics and effectiveness measurement
- `web-ui/src/components/GoalRecitationMetrics.tsx` - Dashboard component for visualization
- `codeframe/persistence/migrations/migration_00X_add_drift_events_table.py` - Database schema for drift event logging

### Modified Files
- `codeframe/core/models.py` - Add `GoalRecitationState` Pydantic model, extend `ContextItemType` enum with GOAL_RECITATION
- `codeframe/lib/sdk_hooks.py` - Integrate tool call tracking and recitation injection in `create_metrics_post_hook()`
- `codeframe/agents/lead_agent.py` - Initialize recitation state in `_assign_and_execute_task()`, handle SYNC blocker escalation for drift
- `codeframe/agents/hybrid_worker.py` - Initialize ToolCallTracker and GoalRecitationMiddleware in `execute_task()`, pass to SDK hooks
- `codeframe/lib/metrics_tracker.py` - Add `record_recitation()` and `record_task_completion()` methods
- `codeframe/agents/definitions/backend-worker.yaml` - Add recitation configuration section
- `codeframe/agents/definitions/frontend-worker.yaml` - Add recitation configuration section
- `codeframe/agents/definitions/test-worker.yaml` - Add recitation configuration section
- `codeframe/agents/definitions/review-worker.yaml` - Add recitation configuration section

---

Execution Information

Branch: main
Commit: 4d894a6

---

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

[traycerai]

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

Previous Plan

Observations

The codebase has a sophisticated multi-agent architecture with context management (HOT/WARM/COLD tiers), task decomposition, and SDK-based tool execution. However, there's no mechanism for goal recitation during long-running tasks. Agents receive tasks via execute_task(task: Task) with static system prompts built at creation time. The context manager handles token limits and flash saves, but doesn't track tool call counts or inject periodic goal reminders. The SDK hooks (file:codeframe/lib/sdk_hooks.py) provide pre/post tool execution points but aren't used for goal recitation.

Approach

Implement a three-layer goal recitation system that prevents agent drift: (1) Tool Call Tracking - add a counter to track tool calls per task execution, (2) Goal Recitation Middleware - inject goal reminders every N tool calls via SDK post-tool hooks, and (3) Context Integration - store goal state as HOT-tier context items. This approach leverages existing SDK hooks and context management without requiring major architectural changes. The recitation will include original task objective, completed steps (inferred from tool outputs), and current focus, positioned at the end of context for maximum attention.

Implementation Steps

1. Audit Current Goal Visibility

Objective: Document how task information flows through agent execution and identify where goal visibility is lost.

Tasks:

• Trace task execution flow from LeadAgent._assign_and_execute_task() (file:codeframe/agents/lead_agent.py, lines 1031-1483) through WorkerAgent.execute_task() (file:codeframe/agents/worker_agent.py, line 67)
• Examine how HybridWorkerAgent (file:codeframe/agents/hybrid_worker.py) constructs prompts for SDK execution
• Review system prompt construction in BackendWorkerAgent._build_system_prompt() (file:codeframe/agents/backend_worker_agent.py, line 119) and similar methods
• Document what task information is available at tool call N vs N+20 by examining SDK conversation history
• Measure context position of task description in typical execution scenarios

Deliverables:

• Document: docs/goal-visibility-audit.md with findings on context degradation patterns
• Identify specific tool call thresholds where task description scrolls out of attention window

---

2. Design Goal Recitation Data Model

Objective: Extend data models to support goal tracking and recitation state.

Tasks:

• Add GoalRecitationState model to file:codeframe/core/models.py:
  • Fields: task_id, tool_call_count, last_recitation_at, completed_actions, remaining_actions, current_focus
• Add recitation_interval configuration to agent definitions (default: 10 tool calls)
• Extend Task model with optional goal_summary field for concise objective statement
• Add GOAL_RECITATION to ContextItemType enum (file:codeframe/core/models.py, line 285)

Deliverables:

• Updated file:codeframe/core/models.py with new models
• Database migration script: codeframe/persistence/migrations/migration_00X_add_goal_recitation.py

---

3. Implement Tool Call Counter

Objective: Track tool calls per task execution to trigger recitation at intervals.

Tasks:

• Create ToolCallTracker class in new file codeframe/lib/tool_call_tracker.py:
  • Methods: increment(task_id), get_count(task_id), reset(task_id), should_recite(task_id, interval)
  • Store counts in memory (dict) with task_id as key
  • Persist counts to database for session resume capability
• Integrate tracker into SDK post-tool hook in file:codeframe/lib/sdk_hooks.py:
  • Modify create_metrics_post_hook() to accept tool_call_tracker parameter
  • Increment counter after each tool execution
  • Return flag indicating if recitation should trigger
• Add tracker instance to AgentPoolManager (file:codeframe/agents/agent_pool_manager.py) and pass to agents

Deliverables:

• New file: codeframe/lib/tool_call_tracker.py
• Updated file:codeframe/lib/sdk_hooks.py with counter integration
• Unit tests: tests/lib/test_tool_call_tracker.py

---

4. Build Goal Recitation Middleware

Objective: Create middleware that injects goal reminders into agent context at intervals.

Tasks:

• Create GoalRecitationMiddleware class in new file codeframe/lib/goal_recitation.py:
  • Method: build_recitation(task: Task, tool_call_count: int, recent_actions: List[str]) -> str
  • Format recitation as structured text with sections: "Original Objective", "Progress So Far", "Remaining Steps", "Current Focus"
  • Keep recitation concise (< 500 tokens) to minimize context overhead
• Integrate with SDK hooks:
  • Modify create_metrics_post_hook() to check if recitation should trigger
  • If yes, call GoalRecitationMiddleware.build_recitation()
  • Inject recitation as a system message or append to conversation history
• Store recitation as HOT-tier context item via ContextManager:
  • Use save_context_item(item_type=ContextItemType.GOAL_RECITATION, content=recitation)
  • Ensure HOT tier placement for maximum visibility

Deliverables:

• New file: codeframe/lib/goal_recitation.py
• Updated file:codeframe/lib/sdk_hooks.py with recitation injection
• Unit tests: tests/lib/test_goal_recitation.py

---

5. Implement Progress Tracking

Objective: Track completed actions and remaining steps to populate recitation content.

Tasks:

• Create ProgressTracker class in file:codeframe/lib/goal_recitation.py:
  • Method: extract_actions_from_tools(tool_outputs: List[Dict]) -> List[str]
  • Parse recent tool outputs (Write, Bash, etc.) to infer completed actions
  • Example: "Write tool → Created file X", "Bash tool → Ran tests"
• Integrate with HybridWorkerAgent (file:codeframe/agents/hybrid_worker.py):
  • After each tool execution, extract action summary
  • Store in GoalRecitationState.completed_actions
• Infer remaining steps from task dependencies:
  • Query task_dependencies table via Database.get_task_dependencies()
  • List incomplete dependent tasks as "remaining steps"

Deliverables:

• ProgressTracker class in file:codeframe/lib/goal_recitation.py
• Integration with HybridWorkerAgent.execute_task()
• Unit tests covering action extraction logic

---

6. Integrate with Lead Agent Coordination Loop

Objective: Enable goal recitation in the multi-agent execution orchestration.

Tasks:

• Modify LeadAgent._assign_and_execute_task() (file:codeframe/agents/lead_agent.py, lines 1031-1483):
  • Initialize GoalRecitationState when assigning task to worker
  • Pass recitation interval configuration to worker agent
  • Store initial goal summary in database
• Update AgentPoolManager._create_hybrid_agent() (file:codeframe/agents/agent_pool_manager.py, line 365):
  • Pass ToolCallTracker and GoalRecitationMiddleware instances to SDK client hooks
  • Configure recitation interval from agent definition or default to 10
• Ensure recitation state persists across agent pool reuse:
  • When agent marked idle via mark_agent_idle(), preserve recitation state
  • When agent reused via get_or_create_agent(), restore recitation state

Deliverables:

• Updated file:codeframe/agents/lead_agent.py with recitation initialization
• Updated file:codeframe/agents/agent_pool_manager.py with middleware integration
• Integration tests: tests/agents/test_goal_recitation_integration.py

---

7. Add Configuration and Tuning

Objective: Make goal recitation configurable and tunable per agent type.

Tasks:

• Add configuration to agent definitions (file:codeframe/agents/definitions/*.yaml):
  • recitation_interval: Number of tool calls between recitations (default: 10)
  • recitation_enabled: Boolean flag to enable/disable (default: true)
  • recitation_template: Custom template for recitation format (optional)
• Add environment variable: CODEFRAME_RECITATION_INTERVAL for global override
• Create configuration loader in file:codeframe/lib/goal_recitation.py:
  • Method: load_recitation_config(agent_type: str) -> Dict
  • Merge agent definition config with environment overrides

Deliverables:

• Updated agent definition files with recitation configuration
• Configuration loader in file:codeframe/lib/goal_recitation.py
• Documentation: docs/goal-recitation-config.md

---

8. Implement Drift Detection (Optional Enhancement)

Objective: Detect when agents are going in circles or off-track.

Tasks:

• Create DriftDetector class in file:codeframe/lib/goal_recitation.py:
  • Method: detect_circular_behavior(tool_history: List[Dict]) -> bool
  • Check for repeated similar tool calls (e.g., same file written 3+ times)
  • Method: detect_objective_drift(task: Task, recent_actions: List[str]) -> float
  • Calculate semantic similarity between task description and recent actions using simple keyword matching
• Integrate with recitation middleware:
  • If drift detected, inject stronger reminder: "⚠️ ATTENTION: You may be drifting from the original objective..."
  • Escalate to SYNC blocker if drift persists for 3+ recitations
• Log drift events for analysis:
  • Store in database table drift_events with task_id, timestamp, drift_score, actions

Deliverables:

• DriftDetector class in file:codeframe/lib/goal_recitation.py
• Integration with recitation middleware
• Unit tests: tests/lib/test_drift_detection.py

---

9. Add Monitoring and Metrics

Objective: Track effectiveness of goal recitation in reducing drift and improving task completion.

Tasks:

• Extend MetricsTracker (file:codeframe/lib/metrics_tracker.py):
  • Track recitation events: record_recitation(task_id, tool_call_count, recitation_content)
  • Track task completion metrics: record_task_completion(task_id, total_tool_calls, recitations_triggered, drift_detected)
• Add dashboard visualization:
  • Create React component: web-ui/src/components/GoalRecitationMetrics.tsx
  • Display: average tool calls per task, recitation frequency, drift detection rate
  • Show before/after comparison if historical data available
• Create analysis script: scripts/analyze-goal-recitation.py:
  • Compare task completion rates for tasks with/without recitation
  • Identify optimal recitation intervals per agent type
  • Generate report: reports/goal-recitation-effectiveness.md

Deliverables:

• Updated file:codeframe/lib/metrics_tracker.py with recitation metrics
• New component: web-ui/src/components/GoalRecitationMetrics.tsx
• Analysis script: scripts/analyze-goal-recitation.py

---

10. Testing and Validation

Objective: Ensure goal recitation works correctly and improves task completion.

Tasks:

• Unit tests for all new components:
  • tests/lib/test_tool_call_tracker.py - counter logic
  • tests/lib/test_goal_recitation.py - recitation building and formatting
  • tests/lib/test_drift_detection.py - drift detection algorithms
• Integration tests:
  • tests/agents/test_goal_recitation_integration.py - end-to-end recitation flow
  • Test scenario: task with 50+ tool calls, verify recitation triggers at intervals
  • Test scenario: agent drift detection and correction
• Manual testing:
  • Create test task requiring 30+ tool calls
  • Monitor recitation injection in agent logs
  • Verify task completion without circular behavior
• Performance testing:
  • Measure context overhead of recitation (should be < 500 tokens per recitation)
  • Verify no significant latency increase per tool call

Deliverables:

• Complete test suite with >85% coverage for new code
• Test report: docs/goal-recitation-test-results.md
• Performance benchmarks in test report

---

Architecture Diagram

sequenceDiagram
    participant LA as LeadAgent
    participant APM as AgentPoolManager
    participant HW as HybridWorkerAgent
    participant SDK as SDKClientWrapper
    participant Hook as SDK Post-Tool Hook
    participant TCT as ToolCallTracker
    participant GRM as GoalRecitationMiddleware
    participant CM as ContextManager

    LA->>APM: assign_task(task)
    APM->>HW: create/reuse agent
    APM->>TCT: initialize counter for task
    HW->>SDK: execute_task(task)
    
    loop Every Tool Call
        SDK->>Hook: post_tool_hook(tool_output)
        Hook->>TCT: increment(task_id)
        Hook->>TCT: should_recite(task_id, interval=10)?
        
        alt Recitation Interval Reached
            TCT-->>Hook: true
            Hook->>GRM: build_recitation(task, count, actions)
            GRM->>CM: save_context_item(GOAL_RECITATION, content)
            CM-->>GRM: item_id
            GRM-->>Hook: recitation_text
            Hook->>SDK: inject recitation as system message
        else Continue Normal Execution
            TCT-->>Hook: false
        end
        
        Hook-->>SDK: continue
    end
    
    SDK-->>HW: task_result
    HW-->>LA: task_completed

Loading

---

Success Criteria

Metric	Target	Measurement Method
Goal visibility maintained	100% of tasks	Audit logs show task objective in context at every recitation
Recitation overhead	< 500 tokens per recitation	Token counter in GoalRecitationMiddleware
Drift detection accuracy	> 80%	Manual review of flagged vs actual drift cases
Task completion improvement	+10% for tasks >20 tool calls	Compare completion rates before/after implementation
No performance regression	< 50ms latency per tool call	Performance benchmarks in tests

---

Configuration Example

# codeframe/agents/definitions/backend-worker.yaml
name: "Backend Worker"
type: "backend"
system_prompt: |
  You are a Backend Worker Agent...
recitation_config:
  enabled: true
  interval: 10  # Recite every 10 tool calls
  template: |
    === GOAL RECITATION ===
    Original Objective: {task.description}
    Progress: {completed_actions}
    Remaining: {remaining_steps}
    Current Focus: {current_subtask}
    ========================

---

Files to Create/Modify

New Files

• codeframe/lib/tool_call_tracker.py - Tool call counting
• codeframe/lib/goal_recitation.py - Recitation middleware and drift detection
• codeframe/persistence/migrations/migration_00X_add_goal_recitation.py - Database schema
• tests/lib/test_tool_call_tracker.py - Unit tests
• tests/lib/test_goal_recitation.py - Unit tests
• tests/lib/test_drift_detection.py - Unit tests
• tests/agents/test_goal_recitation_integration.py - Integration tests
• docs/goal-visibility-audit.md - Audit findings
• docs/goal-recitation-config.md - Configuration guide
• docs/goal-recitation-test-results.md - Test report
• scripts/analyze-goal-recitation.py - Analysis script
• web-ui/src/components/GoalRecitationMetrics.tsx - Dashboard component

Modified Files

• codeframe/core/models.py - Add GoalRecitationState, extend ContextItemType
• codeframe/lib/sdk_hooks.py - Integrate tool call tracking and recitation
• codeframe/agents/lead_agent.py - Initialize recitation state
• codeframe/agents/agent_pool_manager.py - Pass middleware to agents
• codeframe/agents/hybrid_worker.py - Track progress during execution
• codeframe/lib/context_manager.py - Handle GOAL_RECITATION context items
• codeframe/lib/metrics_tracker.py - Track recitation metrics
• codeframe/agents/definitions/*.yaml - Add recitation configuration

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a sophisticated multi-agent architecture with context management (HOT/WARM/COLD tiers), task decomposition, and SDK-based tool execution. However, there's **no mechanism for goal recitation** during long-running tasks. Agents receive tasks via `execute_task(task: Task)` with static system prompts built at creation time. The context manager handles token limits and flash saves, but doesn't track tool call counts or inject periodic goal reminders. The SDK hooks (file:codeframe/lib/sdk_hooks.py) provide pre/post tool execution points but aren't used for goal recitation.

## Approach

Implement a **three-layer goal recitation system** that prevents agent drift: (1) **Tool Call Tracking** - add a counter to track tool calls per task execution, (2) **Goal Recitation Middleware** - inject goal reminders every N tool calls via SDK post-tool hooks, and (3) **Context Integration** - store goal state as HOT-tier context items. This approach leverages existing SDK hooks and context management without requiring major architectural changes. The recitation will include original task objective, completed steps (inferred from tool outputs), and current focus, positioned at the end of context for maximum attention.

## Implementation Steps

### 1. Audit Current Goal Visibility

**Objective:** Document how task information flows through agent execution and identify where goal visibility is lost.

**Tasks:**
- Trace task execution flow from `LeadAgent._assign_and_execute_task()` (file:codeframe/agents/lead_agent.py, lines 1031-1483) through `WorkerAgent.execute_task()` (file:codeframe/agents/worker_agent.py, line 67)
- Examine how `HybridWorkerAgent` (file:codeframe/agents/hybrid_worker.py) constructs prompts for SDK execution
- Review system prompt construction in `BackendWorkerAgent._build_system_prompt()` (file:codeframe/agents/backend_worker_agent.py, line 119) and similar methods
- Document what task information is available at tool call N vs N+20 by examining SDK conversation history
- Measure context position of task description in typical execution scenarios

**Deliverables:**
- Document: `docs/goal-visibility-audit.md` with findings on context degradation patterns
- Identify specific tool call thresholds where task description scrolls out of attention window

---

### 2. Design Goal Recitation Data Model

**Objective:** Extend data models to support goal tracking and recitation state.

**Tasks:**
- Add `GoalRecitationState` model to file:codeframe/core/models.py:
  - Fields: `task_id`, `tool_call_count`, `last_recitation_at`, `completed_actions`, `remaining_actions`, `current_focus`
- Add `recitation_interval` configuration to agent definitions (default: 10 tool calls)
- Extend `Task` model with optional `goal_summary` field for concise objective statement
- Add `GOAL_RECITATION` to `ContextItemType` enum (file:codeframe/core/models.py, line 285)

**Deliverables:**
- Updated file:codeframe/core/models.py with new models
- Database migration script: `codeframe/persistence/migrations/migration_00X_add_goal_recitation.py`

---

### 3. Implement Tool Call Counter

**Objective:** Track tool calls per task execution to trigger recitation at intervals.

**Tasks:**
- Create `ToolCallTracker` class in new file `codeframe/lib/tool_call_tracker.py`:
  - Methods: `increment(task_id)`, `get_count(task_id)`, `reset(task_id)`, `should_recite(task_id, interval)`
  - Store counts in memory (dict) with task_id as key
  - Persist counts to database for session resume capability
- Integrate tracker into SDK post-tool hook in file:codeframe/lib/sdk_hooks.py:
  - Modify `create_metrics_post_hook()` to accept `tool_call_tracker` parameter
  - Increment counter after each tool execution
  - Return flag indicating if recitation should trigger
- Add tracker instance to `AgentPoolManager` (file:codeframe/agents/agent_pool_manager.py) and pass to agents

**Deliverables:**
- New file: `codeframe/lib/tool_call_tracker.py`
- Updated file:codeframe/lib/sdk_hooks.py with counter integration
- Unit tests: `tests/lib/test_tool_call_tracker.py`

---

### 4. Build Goal Recitation Middleware

**Objective:** Create middleware that injects goal reminders into agent context at intervals.

**Tasks:**
- Create `GoalRecitationMiddleware` class in new file `codeframe/lib/goal_recitation.py`:
  - Method: `build_recitation(task: Task, tool_call_count: int, recent_actions: List[str]) -> str`
  - Format recitation as structured text with sections: "Original Objective", "Progress So Far", "Remaining Steps", "Current Focus"
  - Keep recitation concise (< 500 tokens) to minimize context overhead
- Integrate with SDK hooks:
  - Modify `create_metrics_post_hook()` to check if recitation should trigger
  - If yes, call `GoalRecitationMiddleware.build_recitation()`
  - Inject recitation as a system message or append to conversation history
- Store recitation as HOT-tier context item via `ContextManager`:
  - Use `save_context_item(item_type=ContextItemType.GOAL_RECITATION, content=recitation)`
  - Ensure HOT tier placement for maximum visibility

**Deliverables:**
- New file: `codeframe/lib/goal_recitation.py`
- Updated file:codeframe/lib/sdk_hooks.py with recitation injection
- Unit tests: `tests/lib/test_goal_recitation.py`

---

### 5. Implement Progress Tracking

**Objective:** Track completed actions and remaining steps to populate recitation content.

**Tasks:**
- Create `ProgressTracker` class in file:codeframe/lib/goal_recitation.py:
  - Method: `extract_actions_from_tools(tool_outputs: List[Dict]) -> List[str]`
  - Parse recent tool outputs (Write, Bash, etc.) to infer completed actions
  - Example: "Write tool → Created file X", "Bash tool → Ran tests"
- Integrate with `HybridWorkerAgent` (file:codeframe/agents/hybrid_worker.py):
  - After each tool execution, extract action summary
  - Store in `GoalRecitationState.completed_actions`
- Infer remaining steps from task dependencies:
  - Query `task_dependencies` table via `Database.get_task_dependencies()`
  - List incomplete dependent tasks as "remaining steps"

**Deliverables:**
- `ProgressTracker` class in file:codeframe/lib/goal_recitation.py
- Integration with `HybridWorkerAgent.execute_task()`
- Unit tests covering action extraction logic

---

### 6. Integrate with Lead Agent Coordination Loop

**Objective:** Enable goal recitation in the multi-agent execution orchestration.

**Tasks:**
- Modify `LeadAgent._assign_and_execute_task()` (file:codeframe/agents/lead_agent.py, lines 1031-1483):
  - Initialize `GoalRecitationState` when assigning task to worker
  - Pass recitation interval configuration to worker agent
  - Store initial goal summary in database
- Update `AgentPoolManager._create_hybrid_agent()` (file:codeframe/agents/agent_pool_manager.py, line 365):
  - Pass `ToolCallTracker` and `GoalRecitationMiddleware` instances to SDK client hooks
  - Configure recitation interval from agent definition or default to 10
- Ensure recitation state persists across agent pool reuse:
  - When agent marked idle via `mark_agent_idle()`, preserve recitation state
  - When agent reused via `get_or_create_agent()`, restore recitation state

**Deliverables:**
- Updated file:codeframe/agents/lead_agent.py with recitation initialization
- Updated file:codeframe/agents/agent_pool_manager.py with middleware integration
- Integration tests: `tests/agents/test_goal_recitation_integration.py`

---

### 7. Add Configuration and Tuning

**Objective:** Make goal recitation configurable and tunable per agent type.

**Tasks:**
- Add configuration to agent definitions (file:codeframe/agents/definitions/*.yaml):
  - `recitation_interval`: Number of tool calls between recitations (default: 10)
  - `recitation_enabled`: Boolean flag to enable/disable (default: true)
  - `recitation_template`: Custom template for recitation format (optional)
- Add environment variable: `CODEFRAME_RECITATION_INTERVAL` for global override
- Create configuration loader in file:codeframe/lib/goal_recitation.py:
  - Method: `load_recitation_config(agent_type: str) -> Dict`
  - Merge agent definition config with environment overrides

**Deliverables:**
- Updated agent definition files with recitation configuration
- Configuration loader in file:codeframe/lib/goal_recitation.py
- Documentation: `docs/goal-recitation-config.md`

---

### 8. Implement Drift Detection (Optional Enhancement)

**Objective:** Detect when agents are going in circles or off-track.

**Tasks:**
- Create `DriftDetector` class in file:codeframe/lib/goal_recitation.py:
  - Method: `detect_circular_behavior(tool_history: List[Dict]) -> bool`
  - Check for repeated similar tool calls (e.g., same file written 3+ times)
  - Method: `detect_objective_drift(task: Task, recent_actions: List[str]) -> float`
  - Calculate semantic similarity between task description and recent actions using simple keyword matching
- Integrate with recitation middleware:
  - If drift detected, inject stronger reminder: "⚠️ ATTENTION: You may be drifting from the original objective..."
  - Escalate to SYNC blocker if drift persists for 3+ recitations
- Log drift events for analysis:
  - Store in database table `drift_events` with task_id, timestamp, drift_score, actions

**Deliverables:**
- `DriftDetector` class in file:codeframe/lib/goal_recitation.py
- Integration with recitation middleware
- Unit tests: `tests/lib/test_drift_detection.py`

---

### 9. Add Monitoring and Metrics

**Objective:** Track effectiveness of goal recitation in reducing drift and improving task completion.

**Tasks:**
- Extend `MetricsTracker` (file:codeframe/lib/metrics_tracker.py):
  - Track recitation events: `record_recitation(task_id, tool_call_count, recitation_content)`
  - Track task completion metrics: `record_task_completion(task_id, total_tool_calls, recitations_triggered, drift_detected)`
- Add dashboard visualization:
  - Create React component: `web-ui/src/components/GoalRecitationMetrics.tsx`
  - Display: average tool calls per task, recitation frequency, drift detection rate
  - Show before/after comparison if historical data available
- Create analysis script: `scripts/analyze-goal-recitation.py`:
  - Compare task completion rates for tasks with/without recitation
  - Identify optimal recitation intervals per agent type
  - Generate report: `reports/goal-recitation-effectiveness.md`

**Deliverables:**
- Updated file:codeframe/lib/metrics_tracker.py with recitation metrics
- New component: `web-ui/src/components/GoalRecitationMetrics.tsx`
- Analysis script: `scripts/analyze-goal-recitation.py`

---

### 10. Testing and Validation

**Objective:** Ensure goal recitation works correctly and improves task completion.

**Tasks:**
- Unit tests for all new components:
  - `tests/lib/test_tool_call_tracker.py` - counter logic
  - `tests/lib/test_goal_recitation.py` - recitation building and formatting
  - `tests/lib/test_drift_detection.py` - drift detection algorithms
- Integration tests:
  - `tests/agents/test_goal_recitation_integration.py` - end-to-end recitation flow
  - Test scenario: task with 50+ tool calls, verify recitation triggers at intervals
  - Test scenario: agent drift detection and correction
- Manual testing:
  - Create test task requiring 30+ tool calls
  - Monitor recitation injection in agent logs
  - Verify task completion without circular behavior
- Performance testing:
  - Measure context overhead of recitation (should be < 500 tokens per recitation)
  - Verify no significant latency increase per tool call

**Deliverables:**
- Complete test suite with >85% coverage for new code
- Test report: `docs/goal-recitation-test-results.md`
- Performance benchmarks in test report

---

## Architecture Diagram

```mermaid
sequenceDiagram
    participant LA as LeadAgent
    participant APM as AgentPoolManager
    participant HW as HybridWorkerAgent
    participant SDK as SDKClientWrapper
    participant Hook as SDK Post-Tool Hook
    participant TCT as ToolCallTracker
    participant GRM as GoalRecitationMiddleware
    participant CM as ContextManager

    LA->>APM: assign_task(task)
    APM->>HW: create/reuse agent
    APM->>TCT: initialize counter for task
    HW->>SDK: execute_task(task)
    
    loop Every Tool Call
        SDK->>Hook: post_tool_hook(tool_output)
        Hook->>TCT: increment(task_id)
        Hook->>TCT: should_recite(task_id, interval=10)?
        
        alt Recitation Interval Reached
            TCT-->>Hook: true
            Hook->>GRM: build_recitation(task, count, actions)
            GRM->>CM: save_context_item(GOAL_RECITATION, content)
            CM-->>GRM: item_id
            GRM-->>Hook: recitation_text
            Hook->>SDK: inject recitation as system message
        else Continue Normal Execution
            TCT-->>Hook: false
        end
        
        Hook-->>SDK: continue
    end
    
    SDK-->>HW: task_result
    HW-->>LA: task_completed
```

---

## Success Criteria

| Metric | Target | Measurement Method |
|--------|--------|-------------------|
| Goal visibility maintained | 100% of tasks | Audit logs show task objective in context at every recitation |
| Recitation overhead | < 500 tokens per recitation | Token counter in `GoalRecitationMiddleware` |
| Drift detection accuracy | > 80% | Manual review of flagged vs actual drift cases |
| Task completion improvement | +10% for tasks >20 tool calls | Compare completion rates before/after implementation |
| No performance regression | < 50ms latency per tool call | Performance benchmarks in tests |

---

## Configuration Example

```yaml
# codeframe/agents/definitions/backend-worker.yaml
name: "Backend Worker"
type: "backend"
system_prompt: |
  You are a Backend Worker Agent...
recitation_config:
  enabled: true
  interval: 10  # Recite every 10 tool calls
  template: |
    === GOAL RECITATION ===
    Original Objective: {task.description}
    Progress: {completed_actions}
    Remaining: {remaining_steps}
    Current Focus: {current_subtask}
    ========================
```

---

## Files to Create/Modify

### New Files
- `codeframe/lib/tool_call_tracker.py` - Tool call counting
- `codeframe/lib/goal_recitation.py` - Recitation middleware and drift detection
- `codeframe/persistence/migrations/migration_00X_add_goal_recitation.py` - Database schema
- `tests/lib/test_tool_call_tracker.py` - Unit tests
- `tests/lib/test_goal_recitation.py` - Unit tests
- `tests/lib/test_drift_detection.py` - Unit tests
- `tests/agents/test_goal_recitation_integration.py` - Integration tests
- `docs/goal-visibility-audit.md` - Audit findings
- `docs/goal-recitation-config.md` - Configuration guide
- `docs/goal-recitation-test-results.md` - Test report
- `scripts/analyze-goal-recitation.py` - Analysis script
- `web-ui/src/components/GoalRecitationMetrics.tsx` - Dashboard component

### Modified Files
- `codeframe/core/models.py` - Add `GoalRecitationState`, extend `ContextItemType`
- `codeframe/lib/sdk_hooks.py` - Integrate tool call tracking and recitation
- `codeframe/agents/lead_agent.py` - Initialize recitation state
- `codeframe/agents/agent_pool_manager.py` - Pass middleware to agents
- `codeframe/agents/hybrid_worker.py` - Track progress during execution
- `codeframe/lib/context_manager.py` - Handle GOAL_RECITATION context items
- `codeframe/lib/metrics_tracker.py` - Track recitation metrics
- `codeframe/agents/definitions/*.yaml` - Add recitation configuration

---

Execution Information

Branch: main
Commit: 08bbb8e

New Plan

Observations

The codebase has a sophisticated multi-agent architecture with context management (HOT/WARM/COLD tiers), task decomposition, and SDK-based tool execution. However, there's no mechanism for goal recitation during long-running tasks. Agents receive tasks via execute_task(task: Task) with static system prompts built at creation time. The context manager handles token limits and flash saves, but doesn't track tool call counts or inject periodic goal reminders. The SDK hooks (file:codeframe/lib/sdk_hooks.py) provide pre/post tool execution points but aren't used for goal recitation.

---

Approach

Implement a three-layer goal recitation system that prevents agent drift: (1) Tool Call Tracking - add a counter to track tool calls per task execution, (2) Goal Recitation Middleware - inject goal reminders every N tool calls via SDK post-tool hooks, and (3) Context Integration - store goal state as HOT-tier context items. This approach leverages existing SDK hooks and context management without requiring major architectural changes. The recitation will include original task objective, completed steps (inferred from tool outputs), and current focus, positioned at the end of context for maximum attention.

---

Implementation Steps

1. Audit Current Goal Visibility

Objective: Document how task information flows through agent execution and identify where goal visibility is lost.

Tasks:

• Trace task execution flow from LeadAgent._assign_and_execute_task() through HybridWorkerAgent.execute_task() (file:codeframe/agents/hybrid_worker.py, lines 123-205)
• Examine how HybridWorkerAgent._build_execution_prompt() (lines 207-259) constructs prompts with context
• Review system prompt construction in BackendWorkerAgent and similar worker types
• Document what task information is available at tool call N vs N+20 by examining SDK conversation history
• Measure context position of task description in typical execution scenarios

Deliverables:

• Document: docs/goal-visibility-audit.md with findings on context degradation patterns
• Identify specific tool call thresholds where task description scrolls out of attention window

---

2. Design Goal Recitation Data Model

Objective: Extend data models to support goal tracking and recitation state.

Tasks:

• Add GOAL_RECITATION to ContextItemType enum in file:codeframe/core/models.py (line 434)
• Create GoalRecitationState dataclass in file:codeframe/core/models.py:
  • Fields: task_id, tool_call_count, last_recitation_at, completed_actions, remaining_actions, current_focus
• Add recitation_interval configuration field to agent definitions (default: 10 tool calls)
• Extend Task model with optional goal_summary field for concise objective statement

Deliverables:

• Updated file:codeframe/core/models.py with new models and enum value
• Database migration script: codeframe/persistence/migrations/migration_00X_add_goal_recitation.py

---

3. Implement Tool Call Counter

Objective: Track tool calls per task execution to trigger recitation at intervals.

Tasks:

• Create ToolCallTracker class in new file codeframe/lib/tool_call_tracker.py:
  • Methods: increment(task_id), get_count(task_id), reset(task_id), should_recite(task_id, interval)
  • Store counts in memory (dict) with task_id as key
  • Persist counts to database for session resume capability
• Integrate tracker into SDK post-tool hook in file:codeframe/lib/sdk_hooks.py:
  • Modify create_metrics_post_hook() to accept tool_call_tracker parameter
  • Increment counter after each tool execution
  • Return flag indicating if recitation should trigger
• Add tracker instance to HybridWorkerAgent and pass to SDK hooks

Deliverables:

• New file: codeframe/lib/tool_call_tracker.py
• Updated file:codeframe/lib/sdk_hooks.py with counter integration
• Unit tests: tests/lib/test_tool_call_tracker.py

---

4. Build Goal Recitation Middleware

Objective: Create middleware that injects goal reminders into agent context at intervals.

Tasks:

• Create GoalRecitationMiddleware class in new file codeframe/lib/goal_recitation.py:
  • Method: build_recitation(task: Task, tool_call_count: int, recent_actions: List[str]) -> str
  • Format recitation as structured text with sections: "Original Objective", "Progress So Far", "Remaining Steps", "Current Focus"
  • Keep recitation concise (< 500 tokens) to minimize context overhead
• Integrate with SDK hooks:
  • Modify create_metrics_post_hook() to check if recitation should trigger
  • If yes, call GoalRecitationMiddleware.build_recitation()
  • Inject recitation as a system message or append to conversation history
• Store recitation as HOT-tier context item via save_context_item():
  • Use item_type=ContextItemType.GOAL_RECITATION
  • Ensure HOT tier placement for maximum visibility

Deliverables:

• New file: codeframe/lib/goal_recitation.py
• Updated file:codeframe/lib/sdk_hooks.py with recitation injection
• Unit tests: tests/lib/test_goal_recitation.py

---

5. Implement Progress Tracking

Objective: Track completed actions and remaining steps to populate recitation content.

Tasks:

• Create ProgressTracker class in file:codeframe/lib/goal_recitation.py:
  • Method: extract_actions_from_tools(tool_outputs: List[Dict]) -> List[str]
  • Parse recent tool outputs (Write, Bash, etc.) to infer completed actions
  • Example: "Write tool → Created file X", "Bash tool → Ran tests"
• Integrate with HybridWorkerAgent.execute_task():
  • After each tool execution, extract action summary
  • Store in GoalRecitationState.completed_actions
• Infer remaining steps from task dependencies:
  • Query task dependencies via database
  • List incomplete dependent tasks as "remaining steps"

Deliverables:

• ProgressTracker class in file:codeframe/lib/goal_recitation.py
• Integration with HybridWorkerAgent.execute_task()
• Unit tests covering action extraction logic

---

6. Integrate with Lead Agent Coordination Loop

Objective: Enable goal recitation in the multi-agent execution orchestration.

Tasks:

• Modify LeadAgent._assign_and_execute_task() (file:codeframe/agents/lead_agent.py):
  • Initialize GoalRecitationState when assigning task to worker
  • Pass recitation interval configuration to worker agent
  • Store initial goal summary in database
• Update HybridWorkerAgent.execute_task() (file:codeframe/agents/hybrid_worker.py, lines 123-205):
  • Initialize ToolCallTracker at task start
  • Pass tracker to SDK hooks
  • Configure recitation interval from agent definition or default to 10
• Ensure recitation state persists across agent pool reuse:
  • When agent marked idle, preserve recitation state
  • When agent reused, restore recitation state

Deliverables:

• Updated file:codeframe/agents/lead_agent.py with recitation initialization
• Updated file:codeframe/agents/hybrid_worker.py with middleware integration
• Integration tests: tests/agents/test_goal_recitation_integration.py

---

7. Add Configuration and Tuning

Objective: Make goal recitation configurable and tunable per agent type.

Tasks:

• Add configuration to agent definitions (YAML files):
  • recitation_interval: Number of tool calls between recitations (default: 10)
  • recitation_enabled: Boolean flag to enable/disable (default: true)
  • recitation_template: Custom template for recitation format (optional)
• Add environment variable: CODEFRAME_RECITATION_INTERVAL for global override
• Create configuration loader in file:codeframe/lib/goal_recitation.py:
  • Method: load_recitation_config(agent_type: str) -> Dict
  • Merge agent definition config with environment overrides

Deliverables:

• Updated agent definition files with recitation configuration
• Configuration loader in file:codeframe/lib/goal_recitation.py
• Documentation: docs/goal-recitation-config.md

---

8. Implement Drift Detection (Optional Enhancement)

Objective: Detect when agents are going in circles or off-track.

Tasks:

• Create DriftDetector class in file:codeframe/lib/goal_recitation.py:
  • Method: detect_circular_behavior(tool_history: List[Dict]) -> bool
  • Check for repeated similar tool calls (e.g., same file written 3+ times)
  • Method: detect_objective_drift(task: Task, recent_actions: List[str]) -> float
  • Calculate semantic similarity between task description and recent actions using simple keyword matching
• Integrate with recitation middleware:
  • If drift detected, inject stronger reminder: "⚠️ ATTENTION: You may be drifting from the original objective..."
  • Escalate to SYNC blocker if drift persists for 3+ recitations
• Log drift events for analysis:
  • Store in database table drift_events with task_id, timestamp, drift_score, actions

Deliverables:

• DriftDetector class in file:codeframe/lib/goal_recitation.py
• Integration with recitation middleware
• Unit tests: tests/lib/test_drift_detection.py

---

9. Add Monitoring and Metrics

Objective: Track effectiveness of goal recitation in reducing drift and improving task completion.

Tasks:

• Extend MetricsTracker (file:codeframe/lib/metrics_tracker.py):
  • Track recitation events: record_recitation(task_id, tool_call_count, recitation_content)
  • Track task completion metrics: record_task_completion(task_id, total_tool_calls, recitations_triggered, drift_detected)
• Add dashboard visualization:
  • Create React component: web-ui/src/components/GoalRecitationMetrics.tsx
  • Display: average tool calls per task, recitation frequency, drift detection rate
  • Show before/after comparison if historical data available
• Create analysis script: scripts/analyze-goal-recitation.py:
  • Compare task completion rates for tasks with/without recitation
  • Identify optimal recitation intervals per agent type
  • Generate report: reports/goal-recitation-effectiveness.md

Deliverables:

• Updated file:codeframe/lib/metrics_tracker.py with recitation metrics
• New component: web-ui/src/components/GoalRecitationMetrics.tsx
• Analysis script: scripts/analyze-goal-recitation.py

---

10. Testing and Validation

Objective: Ensure goal recitation works correctly and improves task completion.

Tasks:

• Unit tests for all new components:
  • tests/lib/test_tool_call_tracker.py - counter logic
  • tests/lib/test_goal_recitation.py - recitation building and formatting
  • tests/lib/test_drift_detection.py - drift detection algorithms
• Integration tests:
  • tests/agents/test_goal_recitation_integration.py - end-to-end recitation flow
  • Test scenario: task with 50+ tool calls, verify recitation triggers at intervals
  • Test scenario: agent drift detection and correction
• Manual testing:
  • Create test task requiring 30+ tool calls
  • Monitor recitation injection in agent logs
  • Verify task completion without circular behavior
• Performance testing:
  • Measure context overhead of recitation (should be < 500 tokens per recitation)
  • Verify no significant latency increase per tool call

Deliverables:

• Complete test suite with >85% coverage for new code
• Test report: docs/goal-recitation-test-results.md
• Performance benchmarks in test report

---

Architecture Diagram

sequenceDiagram
    participant LA as LeadAgent
    participant APM as AgentPoolManager
    participant HW as HybridWorkerAgent
    participant SDK as SDKClientWrapper
    participant Hook as SDK Post-Tool Hook
    participant TCT as ToolCallTracker
    participant GRM as GoalRecitationMiddleware
    participant CM as ContextManager

    LA->>APM: assign_task(task)
    APM->>HW: create/reuse agent
    APM->>TCT: initialize counter for task
    HW->>SDK: execute_task(task)
    
    loop Every Tool Call
        SDK->>Hook: post_tool_hook(tool_output)
        Hook->>TCT: increment(task_id)
        Hook->>TCT: should_recite(task_id, interval=10)?
        
        alt Recitation Interval Reached
            TCT-->>Hook: true
            Hook->>GRM: build_recitation(task, count, actions)
            GRM->>CM: save_context_item(GOAL_RECITATION, content)
            CM-->>GRM: item_id
            GRM-->>Hook: recitation_text
            Hook->>SDK: inject recitation as system message
        else Continue Normal Execution
            TCT-->>Hook: false
        end
        
        Hook-->>SDK: continue
    end
    
    SDK-->>HW: task_result
    HW-->>LA: task_completed

Loading

---

Success Criteria

Metric	Target	Measurement Method
Goal visibility maintained	100% of tasks	Audit logs show task objective in context at every recitation
Recitation overhead	< 500 tokens per recitation	Token counter in GoalRecitationMiddleware
Drift detection accuracy	> 80%	Manual review of flagged vs actual drift cases
Task completion improvement	+10% for tasks >20 tool calls	Compare completion rates before/after implementation
No performance regression	< 50ms latency per tool call	Performance benchmarks in tests

---

Configuration Example

# codeframe/agents/definitions/backend-worker.yaml
name: "Backend Worker"
type: "backend"
system_prompt: |
  You are a Backend Worker Agent...
recitation_config:
  enabled: true
  interval: 10  # Recite every 10 tool calls
  template: |
    === GOAL RECITATION ===
    Original Objective: {task.description}
    Progress: {completed_actions}
    Remaining: {remaining_steps}
    Current Focus: {current_subtask}
    ========================

---

Files to Create/Modify

New Files

• codeframe/lib/tool_call_tracker.py - Tool call counting
• codeframe/lib/goal_recitation.py - Recitation middleware and drift detection
• codeframe/persistence/migrations/migration_00X_add_goal_recitation.py - Database schema
• tests/lib/test_tool_call_tracker.py - Unit tests
• tests/lib/test_goal_recitation.py - Unit tests
• tests/lib/test_drift_detection.py - Unit tests
• tests/agents/test_goal_recitation_integration.py - Integration tests
• docs/goal-visibility-audit.md - Audit findings
• docs/goal-recitation-config.md - Configuration guide
• docs/goal-recitation-test-results.md - Test report
• scripts/analyze-goal-recitation.py - Analysis script
• web-ui/src/components/GoalRecitationMetrics.tsx - Dashboard component

Modified Files

• codeframe/core/models.py - Add GoalRecitationState, extend ContextItemType
• codeframe/lib/sdk_hooks.py - Integrate tool call tracking and recitation
• codeframe/agents/lead_agent.py - Initialize recitation state
• codeframe/agents/hybrid_worker.py - Pass middleware to agents
• codeframe/lib/metrics_tracker.py - Track recitation metrics
• codeframe/agents/definitions/*.yaml - Add recitation configuration

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a sophisticated multi-agent architecture with context management (HOT/WARM/COLD tiers), task decomposition, and SDK-based tool execution. However, there's **no mechanism for goal recitation** during long-running tasks. Agents receive tasks via `execute_task(task: Task)` with static system prompts built at creation time. The context manager handles token limits and flash saves, but doesn't track tool call counts or inject periodic goal reminders. The SDK hooks (file:codeframe/lib/sdk_hooks.py) provide pre/post tool execution points but aren't used for goal recitation.

---

## Approach

Implement a **three-layer goal recitation system** that prevents agent drift: (1) **Tool Call Tracking** - add a counter to track tool calls per task execution, (2) **Goal Recitation Middleware** - inject goal reminders every N tool calls via SDK post-tool hooks, and (3) **Context Integration** - store goal state as HOT-tier context items. This approach leverages existing SDK hooks and context management without requiring major architectural changes. The recitation will include original task objective, completed steps (inferred from tool outputs), and current focus, positioned at the end of context for maximum attention.

---

## Implementation Steps

### 1. Audit Current Goal Visibility

**Objective:** Document how task information flows through agent execution and identify where goal visibility is lost.

**Tasks:**
- Trace task execution flow from `LeadAgent._assign_and_execute_task()` through `HybridWorkerAgent.execute_task()` (file:codeframe/agents/hybrid_worker.py, lines 123-205)
- Examine how `HybridWorkerAgent._build_execution_prompt()` (lines 207-259) constructs prompts with context
- Review system prompt construction in `BackendWorkerAgent` and similar worker types
- Document what task information is available at tool call N vs N+20 by examining SDK conversation history
- Measure context position of task description in typical execution scenarios

**Deliverables:**
- Document: `docs/goal-visibility-audit.md` with findings on context degradation patterns
- Identify specific tool call thresholds where task description scrolls out of attention window

---

### 2. Design Goal Recitation Data Model

**Objective:** Extend data models to support goal tracking and recitation state.

**Tasks:**
- Add `GOAL_RECITATION` to `ContextItemType` enum in file:codeframe/core/models.py (line 434)
- Create `GoalRecitationState` dataclass in file:codeframe/core/models.py:
  - Fields: `task_id`, `tool_call_count`, `last_recitation_at`, `completed_actions`, `remaining_actions`, `current_focus`
- Add `recitation_interval` configuration field to agent definitions (default: 10 tool calls)
- Extend `Task` model with optional `goal_summary` field for concise objective statement

**Deliverables:**
- Updated file:codeframe/core/models.py with new models and enum value
- Database migration script: `codeframe/persistence/migrations/migration_00X_add_goal_recitation.py`

---

### 3. Implement Tool Call Counter

**Objective:** Track tool calls per task execution to trigger recitation at intervals.

**Tasks:**
- Create `ToolCallTracker` class in new file `codeframe/lib/tool_call_tracker.py`:
  - Methods: `increment(task_id)`, `get_count(task_id)`, `reset(task_id)`, `should_recite(task_id, interval)`
  - Store counts in memory (dict) with task_id as key
  - Persist counts to database for session resume capability
- Integrate tracker into SDK post-tool hook in file:codeframe/lib/sdk_hooks.py:
  - Modify `create_metrics_post_hook()` to accept `tool_call_tracker` parameter
  - Increment counter after each tool execution
  - Return flag indicating if recitation should trigger
- Add tracker instance to `HybridWorkerAgent` and pass to SDK hooks

**Deliverables:**
- New file: `codeframe/lib/tool_call_tracker.py`
- Updated file:codeframe/lib/sdk_hooks.py with counter integration
- Unit tests: `tests/lib/test_tool_call_tracker.py`

---

### 4. Build Goal Recitation Middleware

**Objective:** Create middleware that injects goal reminders into agent context at intervals.

**Tasks:**
- Create `GoalRecitationMiddleware` class in new file `codeframe/lib/goal_recitation.py`:
  - Method: `build_recitation(task: Task, tool_call_count: int, recent_actions: List[str]) -> str`
  - Format recitation as structured text with sections: "Original Objective", "Progress So Far", "Remaining Steps", "Current Focus"
  - Keep recitation concise (< 500 tokens) to minimize context overhead
- Integrate with SDK hooks:
  - Modify `create_metrics_post_hook()` to check if recitation should trigger
  - If yes, call `GoalRecitationMiddleware.build_recitation()`
  - Inject recitation as a system message or append to conversation history
- Store recitation as HOT-tier context item via `save_context_item()`:
  - Use `item_type=ContextItemType.GOAL_RECITATION`
  - Ensure HOT tier placement for maximum visibility

**Deliverables:**
- New file: `codeframe/lib/goal_recitation.py`
- Updated file:codeframe/lib/sdk_hooks.py with recitation injection
- Unit tests: `tests/lib/test_goal_recitation.py`

---

### 5. Implement Progress Tracking

**Objective:** Track completed actions and remaining steps to populate recitation content.

**Tasks:**
- Create `ProgressTracker` class in file:codeframe/lib/goal_recitation.py:
  - Method: `extract_actions_from_tools(tool_outputs: List[Dict]) -> List[str]`
  - Parse recent tool outputs (Write, Bash, etc.) to infer completed actions
  - Example: "Write tool → Created file X", "Bash tool → Ran tests"
- Integrate with `HybridWorkerAgent.execute_task()`:
  - After each tool execution, extract action summary
  - Store in `GoalRecitationState.completed_actions`
- Infer remaining steps from task dependencies:
  - Query task dependencies via database
  - List incomplete dependent tasks as "remaining steps"

**Deliverables:**
- `ProgressTracker` class in file:codeframe/lib/goal_recitation.py
- Integration with `HybridWorkerAgent.execute_task()`
- Unit tests covering action extraction logic

---

### 6. Integrate with Lead Agent Coordination Loop

**Objective:** Enable goal recitation in the multi-agent execution orchestration.

**Tasks:**
- Modify `LeadAgent._assign_and_execute_task()` (file:codeframe/agents/lead_agent.py):
  - Initialize `GoalRecitationState` when assigning task to worker
  - Pass recitation interval configuration to worker agent
  - Store initial goal summary in database
- Update `HybridWorkerAgent.execute_task()` (file:codeframe/agents/hybrid_worker.py, lines 123-205):
  - Initialize `ToolCallTracker` at task start
  - Pass tracker to SDK hooks
  - Configure recitation interval from agent definition or default to 10
- Ensure recitation state persists across agent pool reuse:
  - When agent marked idle, preserve recitation state
  - When agent reused, restore recitation state

**Deliverables:**
- Updated file:codeframe/agents/lead_agent.py with recitation initialization
- Updated file:codeframe/agents/hybrid_worker.py with middleware integration
- Integration tests: `tests/agents/test_goal_recitation_integration.py`

---

### 7. Add Configuration and Tuning

**Objective:** Make goal recitation configurable and tunable per agent type.

**Tasks:**
- Add configuration to agent definitions (YAML files):
  - `recitation_interval`: Number of tool calls between recitations (default: 10)
  - `recitation_enabled`: Boolean flag to enable/disable (default: true)
  - `recitation_template`: Custom template for recitation format (optional)
- Add environment variable: `CODEFRAME_RECITATION_INTERVAL` for global override
- Create configuration loader in file:codeframe/lib/goal_recitation.py:
  - Method: `load_recitation_config(agent_type: str) -> Dict`
  - Merge agent definition config with environment overrides

**Deliverables:**
- Updated agent definition files with recitation configuration
- Configuration loader in file:codeframe/lib/goal_recitation.py
- Documentation: `docs/goal-recitation-config.md`

---

### 8. Implement Drift Detection (Optional Enhancement)

**Objective:** Detect when agents are going in circles or off-track.

**Tasks:**
- Create `DriftDetector` class in file:codeframe/lib/goal_recitation.py:
  - Method: `detect_circular_behavior(tool_history: List[Dict]) -> bool`
  - Check for repeated similar tool calls (e.g., same file written 3+ times)
  - Method: `detect_objective_drift(task: Task, recent_actions: List[str]) -> float`
  - Calculate semantic similarity between task description and recent actions using simple keyword matching
- Integrate with recitation middleware:
  - If drift detected, inject stronger reminder: "⚠️ ATTENTION: You may be drifting from the original objective..."
  - Escalate to SYNC blocker if drift persists for 3+ recitations
- Log drift events for analysis:
  - Store in database table `drift_events` with task_id, timestamp, drift_score, actions

**Deliverables:**
- `DriftDetector` class in file:codeframe/lib/goal_recitation.py
- Integration with recitation middleware
- Unit tests: `tests/lib/test_drift_detection.py`

---

### 9. Add Monitoring and Metrics

**Objective:** Track effectiveness of goal recitation in reducing drift and improving task completion.

**Tasks:**
- Extend `MetricsTracker` (file:codeframe/lib/metrics_tracker.py):
  - Track recitation events: `record_recitation(task_id, tool_call_count, recitation_content)`
  - Track task completion metrics: `record_task_completion(task_id, total_tool_calls, recitations_triggered, drift_detected)`
- Add dashboard visualization:
  - Create React component: `web-ui/src/components/GoalRecitationMetrics.tsx`
  - Display: average tool calls per task, recitation frequency, drift detection rate
  - Show before/after comparison if historical data available
- Create analysis script: `scripts/analyze-goal-recitation.py`:
  - Compare task completion rates for tasks with/without recitation
  - Identify optimal recitation intervals per agent type
  - Generate report: `reports/goal-recitation-effectiveness.md`

**Deliverables:**
- Updated file:codeframe/lib/metrics_tracker.py with recitation metrics
- New component: `web-ui/src/components/GoalRecitationMetrics.tsx`
- Analysis script: `scripts/analyze-goal-recitation.py`

---

### 10. Testing and Validation

**Objective:** Ensure goal recitation works correctly and improves task completion.

**Tasks:**
- Unit tests for all new components:
  - `tests/lib/test_tool_call_tracker.py` - counter logic
  - `tests/lib/test_goal_recitation.py` - recitation building and formatting
  - `tests/lib/test_drift_detection.py` - drift detection algorithms
- Integration tests:
  - `tests/agents/test_goal_recitation_integration.py` - end-to-end recitation flow
  - Test scenario: task with 50+ tool calls, verify recitation triggers at intervals
  - Test scenario: agent drift detection and correction
- Manual testing:
  - Create test task requiring 30+ tool calls
  - Monitor recitation injection in agent logs
  - Verify task completion without circular behavior
- Performance testing:
  - Measure context overhead of recitation (should be < 500 tokens per recitation)
  - Verify no significant latency increase per tool call

**Deliverables:**
- Complete test suite with >85% coverage for new code
- Test report: `docs/goal-recitation-test-results.md`
- Performance benchmarks in test report

---

## Architecture Diagram

```mermaid
sequenceDiagram
    participant LA as LeadAgent
    participant APM as AgentPoolManager
    participant HW as HybridWorkerAgent
    participant SDK as SDKClientWrapper
    participant Hook as SDK Post-Tool Hook
    participant TCT as ToolCallTracker
    participant GRM as GoalRecitationMiddleware
    participant CM as ContextManager

    LA->>APM: assign_task(task)
    APM->>HW: create/reuse agent
    APM->>TCT: initialize counter for task
    HW->>SDK: execute_task(task)
    
    loop Every Tool Call
        SDK->>Hook: post_tool_hook(tool_output)
        Hook->>TCT: increment(task_id)
        Hook->>TCT: should_recite(task_id, interval=10)?
        
        alt Recitation Interval Reached
            TCT-->>Hook: true
            Hook->>GRM: build_recitation(task, count, actions)
            GRM->>CM: save_context_item(GOAL_RECITATION, content)
            CM-->>GRM: item_id
            GRM-->>Hook: recitation_text
            Hook->>SDK: inject recitation as system message
        else Continue Normal Execution
            TCT-->>Hook: false
        end
        
        Hook-->>SDK: continue
    end
    
    SDK-->>HW: task_result
    HW-->>LA: task_completed
```

---

## Success Criteria

| Metric | Target | Measurement Method |
|--------|--------|-------------------|
| Goal visibility maintained | 100% of tasks | Audit logs show task objective in context at every recitation |
| Recitation overhead | < 500 tokens per recitation | Token counter in `GoalRecitationMiddleware` |
| Drift detection accuracy | > 80% | Manual review of flagged vs actual drift cases |
| Task completion improvement | +10% for tasks >20 tool calls | Compare completion rates before/after implementation |
| No performance regression | < 50ms latency per tool call | Performance benchmarks in tests |

---

## Configuration Example

```yaml
# codeframe/agents/definitions/backend-worker.yaml
name: "Backend Worker"
type: "backend"
system_prompt: |
  You are a Backend Worker Agent...
recitation_config:
  enabled: true
  interval: 10  # Recite every 10 tool calls
  template: |
    === GOAL RECITATION ===
    Original Objective: {task.description}
    Progress: {completed_actions}
    Remaining: {remaining_steps}
    Current Focus: {current_subtask}
    ========================
```

---

## Files to Create/Modify

### New Files
- `codeframe/lib/tool_call_tracker.py` - Tool call counting
- `codeframe/lib/goal_recitation.py` - Recitation middleware and drift detection
- `codeframe/persistence/migrations/migration_00X_add_goal_recitation.py` - Database schema
- `tests/lib/test_tool_call_tracker.py` - Unit tests
- `tests/lib/test_goal_recitation.py` - Unit tests
- `tests/lib/test_drift_detection.py` - Unit tests
- `tests/agents/test_goal_recitation_integration.py` - Integration tests
- `docs/goal-visibility-audit.md` - Audit findings
- `docs/goal-recitation-config.md` - Configuration guide
- `docs/goal-recitation-test-results.md` - Test report
- `scripts/analyze-goal-recitation.py` - Analysis script
- `web-ui/src/components/GoalRecitationMetrics.tsx` - Dashboard component

### Modified Files
- `codeframe/core/models.py` - Add `GoalRecitationState`, extend `ContextItemType`
- `codeframe/lib/sdk_hooks.py` - Integrate tool call tracking and recitation
- `codeframe/agents/lead_agent.py` - Initialize recitation state
- `codeframe/agents/hybrid_worker.py` - Pass middleware to agents
- `codeframe/lib/metrics_tracker.py` - Track recitation metrics
- `codeframe/agents/definitions/*.yaml` - Add recitation configuration

---

Execution Information

Branch: main
Commit: 1260477