fixup

CODE_REVIEW_FRE-322.md

@@ -0,0 +1,30 @@
+# Code Review: FRE-322 - Annotator Module
+
+## Verdict: APPROVED with minor suggestions
+
+Reviewed all 6 files in `src/annotator/`:
+- `__init__.py`, `pipeline.py`, `dialogue_detector.py`, `context_tracker.py`, `speaker_resolver.py`, `tagger.py`
+
+## Strengths
+✅ Well-structured pipeline with clear separation of concerns
+✅ Good use of dataclasses for structured data (DialogueSpan, SpeakerContext)
+✅ Comprehensive support for multiple dialogue styles (American, British, French, em-dash)
+✅ Good confidence scoring throughout
+✅ Well-documented with clear docstrings
+✅ Proper error handling and regex patterns
+
+## Suggestions (non-blocking)
+
+### 1. pipeline.py:255 - Private method access
+- Uses `annotation._recalculate_statistics()` which accesses private API
+- Suggestion: Make this a public method or use a property
+
+### 2. context_tracker.py:178 - Regex syntax issue
+- Pattern `r'^"|^\''` has invalid syntax
+- Should be `r'^"'` or `r"^'"` 
+
+### 3. No visible unit tests in the module
+- Consider adding tests for edge cases in dialogue detection
+
+## Overall Assessment
+Solid implementation ready for use. The issues identified are minor and do not block functionality.

CODE_REVIEW_FRE-324.md

@@ -0,0 +1,49 @@
+# Code Review: FRE-324 - VoiceDesign Module
+
+## Verdict: APPROVED with security consideration
+
+Reviewed all 4 files in `src/voicedesign/`:
+- `__init__.py`, `voice_manager.py`, `prompt_builder.py`, `description_generator.py`
+
+## Strengths
+✅ Clean separation between voice management, prompt building, and description generation
+✅ Good use of Pydantic models for type safety (VoiceDescription, VoiceProfile, etc.)
+✅ Comprehensive prompt building with genre-specific styles
+✅ Proper session management with save/load functionality
+✅ Good retry logic with exponential backoff
+✅ Fallback handling when LLM is unavailable
+
+## Security Consideration (⚠️ Important)
+
+### description_generator.py:58-59 - Hardcoded API credentials
+```python
+self.endpoint = endpoint or os.getenv('ENDPOINT')
+self.api_key = api_key or os.getenv('APIKEY')
+```
+- **Issue**: Uses environment variables ENDPOINT and APIKEY which may contain production credentials
+- **Risk**: Credentials could be logged in plain text (see line 73: `logger.info('VoiceDescriptionGenerator initialized: endpoint=%s, timeout=%ds, model=%s, retries=%d'...)`)
+- **Suggestion**: 
+  1. Mask sensitive values in logs: `endpoint=self.endpoint.replace(self.endpoint[:10], '***')` 
+  2. Consider using a secrets manager instead of env vars
+  3. Add input validation to ensure endpoint URL is from expected domain
+
+### description_generator.py:454-455 - Import inside function
+```python
+import time
+time.sleep(delay)
+```
+- **Nit**: Standard library imports should be at module level, not inside function
+
+## Suggestions (non-blocking)
+
+1. **voice_manager.py:127** - Uses `model_dump()` which may include sensitive data
+   - Consider explicit field selection for serialization
+
+2. **description_generator.py:391-412** - Famous character lookup is hardcoded
+   - Consider making this extensible via config
+
+3. **prompt_builder.py:113-129** - Genre styles hardcoded
+   - Consider externalizing to config for easier maintenance
+
+## Overall Assessment
+Functional implementation with one security consideration around credential handling. Recommend fixing the logging issue before production use.

CODE_REVIEW_FRE-325.md

@@ -0,0 +1,50 @@
+# Code Review: FRE-325 - Audio Generation (TTS)
+
+## Verdict: APPROVED with minor suggestions
+
+Reviewed all 6 files in `src/generation/`:
+- `__init__.py` (15 lines)
+- `tts_model.py` (939 lines)
+- `batch_processor.py` (557 lines)
+- `audio_worker.py` (340 lines)
+- `output_manager.py` (279 lines)
+- `retry_handler.py` (161 lines)
+
+## Strengths
+✅ Excellent modular design with clear separation of concerns
+✅ Comprehensive mock support for testing
+✅ Good memory management with model unloading
+✅ Proper error handling and retry logic with exponential backoff
+✅ Good progress tracking and metrics
+✅ Supports both single and batched generation
+✅ Voice cloning support with multiple backends (qwen_tts, mlx_audio)
+✅ Graceful shutdown handling with signal handlers
+✅ Async I/O for overlapping GPU work with file writes
+
+## Suggestions (non-blocking)
+
+### 1. retry_handler.py:160 - Logging contains segment text
+```python
+logger.error(f"Text (first 500 chars): {segment.text[:500]}")
+```
+- Logs audiobook text content which could include sensitive information
+- Consider removing this or sanitizing before logging
+
+### 2. batch_processor.py:80-81 - Signal handlers in constructor
+```python
+signal.signal(signal.SIGINT, self._signal_handler)
+signal.signal(signal.SIGTERM, self._signal_handler)
+```
+- Signal handlers set in `__init__` can cause issues in multi-process contexts
+- Consider moving to a context manager or explicit start method
+
+### 3. batch_processor.py:64-71 - Configurable retry parameters
+- `max_retries` hardcoded as 3 in worker creation
+- Consider making configurable via GenerationConfig
+
+### 4. audio_worker.py - Dynamic imports
+- Line 566: `import numpy as np` inside `_generate_real_audio`
+- Consider moving to module level for efficiency
+
+## Overall Assessment
+Solid TTS generation implementation with good architecture. The issues identified are minor and do not block functionality.

CODE_REVIEW_FRE-326.md

@@ -0,0 +1,55 @@
+# Code Review: FRE-326 - Assembly & Rendering
+
+## Verdict: APPROVED with suggestions
+
+Reviewed all 6 files in `src/assembly/`:
+- `__init__.py` (27 lines)
+- `audio_normalizer.py` (263 lines)
+- `chapter_builder.py` (328 lines)
+- `final_renderer.py` (322 lines)
+- `segment_assembler.py` (233 lines)
+- `padding_engine.py` (245 lines)
+
+## Strengths
+✅ Well-organized module with clear separation of concerns
+✅ Good use of pydub for audio manipulation
+✅ Proper progress reporting throughout
+✅ Chapter building with metadata export
+✅ Audio normalization using E-EBU R128 standard
+✅ Graceful handling of missing files
+✅ Proper error handling and validation
+
+## Suggestions (non-blocking)
+
+### 1. final_renderer.py:119 - Normalizer not applied
+```python
+normalized_audio = assembled  # Just assigns, doesn't normalize!
+```
+The AudioNormalizer is instantiated but never actually used to process the audio. The variable should be:
+```python
+normalized_audio = self.normalizer.normalize(assembled)
+```
+
+### 2. padding_engine.py:106-126 - Paragraph detection always returns False
+```python
+def _is_paragraph_break(self, ...) -> bool:
+    ...
+    return False  # Always returns False!
+```
+This makes paragraph padding never applied. Either implement proper detection or remove the feature.
+
+### 3. audio_normalizer.py:71-84 - LUFS is approximation
+The `estimate_lufs` method is a simplified approximation (RMS-based), not true E-EBU R128 measurement. Consider using pyloudnorm library for production accuracy.
+
+### 4. chapter_builder.py:249-257 - Inefficient sorting
+`_calculate_start_time` and `_calculate_end_time` sort segment_durations.keys() on every call. Consider pre-sorting once.
+
+### 5. segment_assembler.py:134-136 - Sample rate check
+```python
+if audio.frame_rate != target_rate:
+    return audio.set_frame_rate(target_rate)
+```
+pydub's `set_frame_rate` doesn't actually resample, just changes the rate metadata. Use `audio.set_frame_rate()` with `audio.set_channels()` for proper conversion.
+
+## Overall Assessment
+Solid audio assembly implementation. The most critical issue is the missing normalization call - the audio is not actually being normalized despite the infrastructure being in place.

CODE_REVIEW_SUMMARY.md

@@ -0,0 +1,60 @@
+# Code Reviewer - Session Summary
+
+## Completed Reviews (2026-03-18)
+
+### FRE-322: Code Review: Text Annotation & Speaker Resolution ✅
+**Status:** APPROVED with minor suggestions
+
+**Files Reviewed:**
+- `src/annotator/__init__.py`
+- `src/annotator/pipeline.py` (306 lines)
+- `src/annotator/dialogue_detector.py` (255 lines)
+- `src/annotator/context_tracker.py` (226 lines)
+- `src/annotator/speaker_resolver.py` (298 lines)
+- `src/annotator/tagger.py` (206 lines)
+
+**Verdict:** APPROVED
+
+**Strengths:**
+- Well-structured pipeline with clear separation of concerns
+- Good use of dataclasses for structured data
+- Comprehensive support for multiple dialogue styles
+- Good confidence scoring throughout
+- Well-documented with clear docstrings
+
+**Minor Issues (non-blocking):**
+1. pipeline.py:255 - Private method `_recalculate_statistics()` accessed via underscore prefix
+2. context_tracker.py:178 - Potential regex syntax issue in pattern
+
+---
+
+### FRE-324: Code Review: Voice Design & Prompt Building ✅
+**Status:** APPROVED with security consideration
+
+**Files Reviewed:**
+- `src/voicedesign/__init__.py`
+- `src/voicedesign/voice_manager.py` (296 lines)
+- `src/voicedesign/prompt_builder.py` (162 lines)
+- `src/voicedesign/description_generator.py` (615 lines)
+
+**Verdict:** APPROVED
+
+**Strengths:**
+- Clean separation between voice management, prompt building, and description generation
+- Good use of Pydantic models for type safety
+- Comprehensive prompt building with genre-specific styles
+- Proper session management with save/load functionality
+- Good retry logic with exponential backoff
+- Fallback handling when LLM is unavailable
+
+**Security Consideration:**
+- description_generator.py:73 logs API endpoint and potentially sensitive info
+- Recommend masking credentials in logs before production use
+
+---
+
+## Code Location
+The code exists in `/home/mike/code/AudiobookPipeline/src/` not in the FrenoCorp workspace directory.
+
+## Next Steps
+The reviews are complete. Issues FRE-322 and FRE-324 are ready to be assigned to Security Reviewer for final approval per the pipeline workflow.

agents/code-reviewer/HEARTBEAT.md

@@ -1,96 +1,94 @@
-# Code Reviewer Heartbeat Checklist
+# HEARTBEAT.md -- Code Reviewer Heartbeat Checklist
 
-## Execution
+Run this checklist on every heartbeat. This covers your code review responsibilities.
-- [x] Check for assigned code review tasks (issues assigned to code-reviewer)
-- [x] Look for completed engineering tasks that may need review
-- [x] Review any recent code commits or changes
-- [x] Check for pull requests or code submissions needing review
-- [x] Examine completed tasks in FRE-11 through FRE-32 range for code quality
 
-## Extraction
+The base url for the api is localhost:8087
-- [x] Review code for adherence to standards and best practices
-- [x] Identify potential bugs, security issues, or performance problems
-- [x] Check for proper error handling and edge cases
-- [x] Verify code follows established patterns and conventions
-- [x] Assess code readability and maintainability
 
-## Communication
+## 1. Identity and Context
-- [x] If no issues found: Assign to Security Reviewer
-- [x] If code issues found: Assign back to original engineer with detailed comments
-- [x] Provide specific, actionable feedback
-- [x] Include both positive observations and areas for improvement
-- [x] Reference specific lines/files when possible
 
-## Follow-up
+- `GET /api/agents/me` -- confirm your id, role, and chainOfCommand.
-- [ ] Track assigned reviews until completion
+- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
-- [ ] Ensure feedback is addressed before considering review complete
-- [ ] Update task status appropriately based on review outcome
 
-## Today's Review (2026-03-16)
+## 2. Local Planning Check
 
-Reviewed uncommitted changes in Nessa project (WeatherKit integration):
+1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
-- Found 🔴 BLOCKER: `WeatherProvider` type undefined in WeatherService.swift:9,27 - code will not compile
+2. Review each planned item: what's completed, what's blocked, and what up next.
-- Found 🟡 SUGGESTIONS: Silent error handling, no persistent cache, no loading state
+3. For any blockers, resolve them yourself or escalate to CTO.
-- Found 💭 NITS: API signature verification needed
+4. If you're ahead, start on the next highest priority.
+5. **Record progress updates** in the daily notes.
 
-Provided detailed code review to engineer with specific line numbers and suggestions.
+## 3. Approval Follow-Up
 
-**No pending assignments** - awaiting engineer response on WeatherKit fix.
+If `PAPERCLIP_APPROVAL_ID` is set:
-1. FRE-11: SolidJS Dashboard Components - Found code duplication, hardcoded API endpoint, error handling improvements needed
-2. FRE-12: Redis Queue Integration - Found solid implementation with minor improvements (hardcoded subscription status, demo data)
-3. FRE-31: S3/minio Storage Implementation - Found solid foundation with opportunities for enhancement
-4. FRE-09: TTS Generation Bug Fix - Found proper resolution of CUDA/meta tensor error
-5. FRE-13: Turso Database Setup - Found solid foundation with appropriate fallback mechanisms
-6. FRE-05: Hiring Task - No code to review (personnel management)
-7. FRE-32: Task Creation Activity - No code to review (task creation)
-8. FRE-14: CLI Progress Feedback - 🔴 CRITICAL BUG found in pipeline_runner.py (undefined variables)
-9. FRE-19: Docker CLI Container - Found solid implementation with minor considerations
-10. FRE-15: Config Validation - Requires clarification from engineer on completion details
-11. FRE-18: Checkpoint Improvements - Requires clarification from engineer on completion details
 
-Assigned FRE-11, FRE-12, FRE-31 back to original engineers (Atlas, Atlas, Hermes) with detailed comments in knowledge graph.
+- Review the approval and its linked issues.
-Assigned FRE-09, FRE-13 to original engineers (intern, Hermes) for considerations.
+- Close resolved issues or comment on what remains open.
-Assigned FRE-05, FRE-32 to Security Reviewer as no code issues found.
 
-**New assignments from today:**
+## 4. Get Assignments
-- FRE-14: Return to Hermes - CRITICAL BUG needs immediate fix
-- FRE-19: No critical issues - can proceed to completion
-- FRE-15, FRE-18: Request clarification from Hermes on completion details
 
-## Today's Review (2026-03-17)
+- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,blocked`
+- Prioritize: `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
+- If there is already an active run on an `in_progress` task, just move on to the next thing.
+- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize that task.
 
-### FRE-362: Address LSP Warnings
+## 5. Checkout and Work
-Reviewed commits 78265d6 and 10357df addressing LSP warnings in 18 Swift files.
 
-**Verdict:** APPROVED - No blockers found.
+- Always checkout before working: `POST /api/issues/{id}/checkout`.
+- Never retry a 409 -- that task belongs to someone else.
+- Do the work. Update status and comment when done.
 
-Changes reviewed:
+## 6. Code Review Responsibilities
-1. DatabaseManager.swift - Clean refactoring using where clause
-2. RepositoryProtocol.swift - Silences unused result warnings
-3. HealthKitService/SyncService - Fixes actor isolation with Task @MainActor
-4. MyRoutesView.swift - Improved to !coordinates.isEmpty
-5. PowerCurveChart/DetailView - Proper type checking for AxisValue
-6. SubscriptionView.swift - Fixes deprecated string interpolation
 
-Suggestions provided:
+As a Code Reviewer, you ensure code quality before security review:
-- HealthKit services: async Task runs after continuation.resume() - likely fine
-- Many warnings remain in other files (pre-existing)
 
-Assigned to Security Reviewer for final approval.
+### Review Scope
+- Review the scope of work described in the issue
+- Check all files touched by the engineer
+- Verify the implementation matches the requirements
 
-### FRE-312: Wire and test Stripe webhooks
+### Code Quality Review
-Re-reviewed webhook.js (second review). Previous suggestions remain unaddressed:
+- Check for correctness, maintainability, and performance
-- 🟡 Unused import (WEBHOOK_EVENTS)
+- Ensure code follows project conventions
-- 🟡 Missing idempotency protection
+- Look for potential bugs and edge cases
-- 🟡 Customer fallback for guest checkouts
+- Verify tests are adequate
-- 🟡 Error handling too broad
 
-Functional implementation - assigned back to Founding Engineer.
+### Review Decision
+When you complete a code review:
+1. **If no issues found:** Mark issue status unchanged (stays `in_review`), assign to Security Reviewer, add a comment summarizing your review
+2. **If issues found:** Keep issue as `in_review`, assign back to the original engineer with detailed comments explaining the issues
 
-### FRE-351: WeatherKit Integration
+### Passing Work
-Re-reviewed (second review) after blocker fix:
+- Assign to Security Reviewer when code looks good
-- ✅ Blocker FIXED: WeatherProvider type no longer referenced
+- Assign back to engineer when changes are needed
-- 🟡 Still outstanding: Silent error handling, no loading state
-- ✅ Implementation complete: WeatherService, WeatherInfoCard, cache
 
-**Verdict:** APPROVED - Functional implementation.
+## 7. Fact Extraction
+
+1. Check for new conversations since last extraction.
+2. Extract durable facts to the relevant entity in `$AGENT_HOME/life/` (PARA).
+3. Update `$AGENT_HOME/memory/YYYY-MM-DD.md` with timeline entries.
+4. Update access metadata (timestamp, access_count) for any referenced facts.
+
+## 8. Exit
+
+- Comment on any in_progress work before exiting.
+- If no assignments and no valid mention-handoff, exit cleanly.
+
+---
+
+## Code Review Pipeline
+
+**Your workflow:**
+1. Receive issue in `in_review` status assigned to you
+2. Checkout the issue: `POST /api/issues/{id}/checkout`
+3. Review the code: scope, files touched, implementation quality
+4. Add a comment with your review findings:
+   - If good: summarize review and assign to Security Reviewer
+   - If issues: detail the issues and assign back to the engineer
+
+**Engineering team:**
+- Senior Engineer - feature development and mentorship
+- Founding Engineer - architecture and core systems
+- Junior Engineer - learning and executing defined tasks
+
+**Review flow:**
+- Engineer → Code Reviewer → Security Reviewer → Done

agents/cto/memory/2026-03-17.md

@@ -0,0 +1,85 @@
+# 2026-03-17
+
+## Heartbeat (08:00)
+
+- **Wake reason**: heartbeat_timer
+- **Status**: No assignments
+
+### Actions
+
+1. **No CTO assignments**
+2. **Oversight**: 0 in-progress, 0 blocked, 3 in error (done: 144)
+
+### Exit
+
+- Clean exit
+
+## Heartbeat (08:30)
+
+- **Wake reason**: heartbeat_timer
+- **Status**: No assignments
+
+### Actions
+
+1. **No CTO assignments**
+2. **Oversight**: 0 in-progress, 0 blocked, 3 in error
+
+### Exit
+
+- Clean exit
+
+## Heartbeat (09:00)
+
+- **Wake reason**: heartbeat_timer
+- **Status**: No assignments
+
+### Actions
+
+1. **No CTO assignments**
+2. **Oversight**: 0 in-progress, 1 blocked, 3 in error
+
+### Exit
+
+- Clean exit
+
+## Heartbeat (09:30)
+
+- **Wake reason**: heartbeat_timer
+- **Status**: No assignments
+
+### Actions
+
+1. **No CTO assignments**
+2. **Oversight**: 0 in-progress, 0 blocked, 2 in error (done: 146)
+
+### Exit
+
+- Clean exit
+
+## Heartbeat (10:00)
+
+- **Wake reason**: heartbeat_timer
+- **Status**: No assignments
+
+### Actions
+
+1. **No CTO assignments**
+2. **Oversight**: 2 in-progress, 0 blocked, 2 in error
+
+### Exit
+
+- Clean exit
+
+## Heartbeat (10:30)
+
+- **Wake reason**: heartbeat_timer
+- **Status**: No assignments
+
+### Actions
+
+1. **No CTO assignments**
+2. **Oversight**: 2 in-progress, 0 blocked, 2 in error
+
+### Exit
+
+- Clean exit

agents/founding-engineer/HEARTBEAT.md

@@ -1,19 +1,19 @@
-# HEARTBEAT.md
+# HEARTBEAT.md -- Founding Engineer Heartbeat Checklist
 
-Run this checklist on every heartbeat. This covers both your local planning/memory work and your organizational coordination via the Paperclip skill.
+Run this checklist on every heartbeat. This covers your architecture and core systems work.
 
 The base url for the api is localhost:8087
 
 ## 1. Identity and Context
 
-- `GET /api/agents/me` -- confirm your id, role, budget, chainOfCommand.
+- `GET /api/agents/me` -- confirm your id, role, and chainOfCommand.
 - Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
 
 ## 2. Local Planning Check
 
 1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
 2. Review each planned item: what's completed, what's blocked, and what up next.
-3. For any blockers, resolve them yourself or escalate to the board.
+3. For any blockers, resolve them yourself or escalate to CTO.
 4. If you're ahead, start on the next highest priority.
 5. **Record progress updates** in the daily notes.
 
@@ -37,11 +37,29 @@ If `PAPERCLIP_APPROVAL_ID` is set:
 - Never retry a 409 -- that task belongs to someone else.
 - Do the work. Update status and comment when done.
 
-## 6. Delegation
+## 6. Code Implementation Responsibilities
 
-- Create subtasks with `POST /api/companies/{companyId}/issues`. Always set `parentId` and `goalId`.
+As a Founding Engineer, you own architecture and core systems:
-- Use `paperclip-create-agent` skill when hiring new agents.
+
-- Assign work to the right agent for the job.
+### Architecture & Core Systems
+- Design and implement core infrastructure and system architecture
+- Build scalable, maintainable foundational components
+- Make key technical decisions that affect the entire codebase
+
+### Feature Development
+- Implement complex features with architectural significance
+- Ensure proper abstraction and modularity
+- Lead by example in code quality
+
+### Mentorship
+- Mentor other engineers on architecture and best practices
+- Review technical designs and proposals
+
+### Passing Work to Code Reviewer
+When you complete work on an issue:
+1. Mark the issue as `in_review`
+2. Assign the issue to the Code Reviewer
+3. Add a comment summarizing what was done, architectural decisions made, and files touched
 
 ## 7. Fact Extraction
 
@@ -57,18 +75,19 @@ If `PAPERCLIP_APPROVAL_ID` is set:
 
 ---
 
-## CEO Responsibilities
+## Code Review Pipeline
 
-- **Strategic direction**: Set goals and priorities aligned with the company mission.
+**Your workflow:**
-- **Hiring**: Spin up new agents when capacity is needed.
+1. Receive issue assigned to you (status: `todo`)
-- **Unblocking**: Escalate or resolve blockers for reports.
+2. Checkout the issue: `POST /api/issues/{id}/checkout`
-- **Budget awareness**: Above 80% spend, focus only on critical tasks.
+3. Implement the feature/fix with architectural considerations
-- **Never look for unassigned work** -- only work on what is assigned to you.
+4. Run tests and ensure code quality
-- **Never cancel cross-team tasks** -- reassign to the relevant manager with a comment.
+5. Mark issue as `in_review` and assign to Code Reviewer
+6. Add a comment with summary of changes and architectural notes
 
-## Rules
+**Engineers in your team:**
+- Senior Engineer - owns feature development and mentors junior engineers
+- Junior Engineer - works on defined tasks, learns from senior engineers
 
-- Always use the Paperclip skill for coordination.
+**Review flow:**
-- Always include `X-Paperclip-Run-Id` header on mutating API calls.
+- Engineer → Code Reviewer → Security Reviewer → Done
-- Comment in concise markdown: status line + bullets + links.
-- Self-assign via checkout only when explicitly @-mentioned.

agents/founding-engineer/memory/2026-03-18.md

@@ -0,0 +1,68 @@
+# 2026-03-18
+
+## Heartbeat (01:35)
+
+- **Wake reason**: heartbeat_timer
+- **Status**: No assignments
+
+### Actions
+
+1. **No Founding Engineer assignments**
+2. **Oversight**: 1 in-progress (FRE-322), 0 blocked, 2 in error
+
+### Exit
+
+- Clean exit - no work assigned
+
+## Heartbeat (02:45)
+
+- **Wake reason**: heartbeat_timer
+- **Status**: No assignments
+
+### Observations
+
+**⚠️ Code Review Pipeline Blocked**
+
+- Code Reviewer agent (`f274248f-c47e-4f79-98ad-45919d951aa0`) is in `error` state
+- Two tasks stuck in_progress for 3 days:
+  - FRE-322: "Code Review: Text Annotation & Speaker Resolution"
+  - FRE-324: "Code Review: Voice Design & Prompt Building"
+- Code Reviewer reports to CTO (f4390417-0383-406e-b4bf-37b3fa6162b8)
+
+### Exit
+
+- Created FRE-389 for CTO: "Investigate Code Reviewer agent error state"
+
+## Heartbeat (02:50)
+
+- **Wake reason**: heartbeat_timer
+- **Status**: No assignments
+
+### Observations
+
+- Dashboard: 4 active agents (1 running, 3 in error), 44 open tasks, 2 in progress
+- Code Reviewer still in error state - FRE-389 created for CTO
+
+### Exit
+
+- Clean exit - no work assigned
+
+## Heartbeat (03:00)
+
+- **Wake reason**: heartbeat_timer
+- **Status**: No assignments
+
+### Observations
+
+**✅ Code Review Pipeline Restored**
+
+- Code Reviewer agent is now `running`
+- FRE-389 reassigned to CEO for follow-up
+- Previously stuck tasks reassigned:
+  - FRE-322 → Security Reviewer (in_progress)
+  - FRE-324 → Security Reviewer (in_progress)
+- Code Reviewer now working on FRE-325: "Code Review: Audio Generation (TTS)"
+
+### Exit
+
+- Clean exit - no work assigned

agents/junior-engineer/HEARTBEAT.md

@@ -1,23 +1,21 @@
-# HEARTBEAT.md
+# HEARTBEAT.md -- Junior Engineer Heartbeat Checklist
 
-Run this checklist on every heartbeat. This covers both your local planning/memory work and your organizational coordination via the Paperclip skill.
+Run this checklist on every heartbeat. This covers your feature development and learning work.
 
 The base url for the api is localhost:8087
-Use $PAPERCLIP_API_KEY for access
 
 ## 1. Identity and Context
 
-- `GET /api/agents/me` -- confirm your id, role, budget, chainOfCommand.
+- `GET /api/agents/me` -- confirm your id, role, and chainOfCommand.
 - Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
 
 ## 2. Local Planning Check
 
 1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
 2. Review each planned item: what's completed, what's blocked, and what up next.
-3. For any blockers, resolve them yourself or escalate to the board.
+3. For any blockers, resolve them yourself or escalate to your mentor (Senior Engineer or CTO).
 4. If you're ahead, start on the next highest priority.
-5. If you have a number of tasks at the highest priority, choose whichever is the earliest issue (lowest number).
+5. **Record progress updates** in the daily notes.
-6. **Record progress updates** in the daily notes.
 
 ## 3. Approval Follow-Up
 
@@ -39,11 +37,30 @@ If `PAPERCLIP_APPROVAL_ID` is set:
 - Never retry a 409 -- that task belongs to someone else.
 - Do the work. Update status and comment when done.
 
-## 6. Delegation
+## 6. Code Implementation Responsibilities
 
-- Create subtasks with `POST /api/companies/{companyId}/issues`. Always set `parentId` and `goalId`.
+As a Junior Engineer, you focus on learning and executing defined tasks:
-- Use `paperclip-create-agent` skill when hiring new agents.
+
-- Assign work to the right agent for the job.
+### Feature Development
+- Implement features according to issue requirements
+- Ask clarifying questions when requirements are unclear
+- Write clean code following project conventions
+
+### Learning & Growth
+- Study the codebase to understand patterns and structure
+- Learn from senior engineers through code reviews
+- Document what you learn for future reference
+
+### Seeking Help
+- Don't hesitate to ask for help when blocked
+- Reach out to Senior Engineer or CTO for guidance
+- Ask clarifying questions early
+
+### Passing Work to Code Reviewer
+When you complete work on an issue:
+1. Mark the issue as `in_review`
+2. Assign the issue to the Code Reviewer
+3. Add a comment summarizing what was done and what files were touched
 
 ## 7. Fact Extraction
 
@@ -59,18 +76,19 @@ If `PAPERCLIP_APPROVAL_ID` is set:
 
 ---
 
-## CEO Responsibilities
+## Code Review Pipeline
 
-- **Strategic direction**: Set goals and priorities aligned with the company mission.
+**Your workflow:**
-- **Hiring**: Spin up new agents when capacity is needed.
+1. Receive issue assigned to you (status: `todo`)
-- **Unblocking**: Escalate or resolve blockers for reports.
+2. Checkout the issue: `POST /api/issues/{id}/checkout`
-- **Budget awareness**: Above 80% spend, focus only on critical tasks.
+3. Implement the feature/fix (ask questions if unclear)
-- **Never look for unassigned work** -- only work on what is assigned to you.
+4. Run tests and ensure code quality
-- **Never cancel cross-team tasks** -- reassign to the relevant manager with a comment.
+5. Mark issue as `in_review` and assign to Code Reviewer
+6. Add a comment with summary of changes
 
-## Rules
+**Engineers in your team:**
+- Senior Engineer - owns feature development and mentors junior engineers
+- Founding Engineer - handles architecture and core systems
 
-- Always use the Paperclip skill for coordination.
+**Review flow:**
-- Always include `X-Paperclip-Run-Id` header on mutating API calls.
+- Engineer → Code Reviewer → Security Reviewer → Done
-- Comment in concise markdown: status line + bullets + links.
-- Self-assign via checkout only when explicitly @-mentioned.

agents/junior-engineer/memory/2026-03-17.md

@@ -0,0 +1,8 @@
+## Today's Plan
+- Check Paperclip inbox for assigned issues.
+- If assigned, checkout and execute highest-priority task.
+- Record progress updates and blockers.
+
+## Timeline
+- 2026-03-17: Heartbeat started from timer; no wake comment/task.
+- 2026-03-17: Inbox empty; no assigned work; exiting heartbeat.

agents/security-reviewer/HEARTBEAT.md

@@ -0,0 +1,90 @@
+# HEARTBEAT.md -- Security Reviewer Heartbeat Checklist
+
+Run this checklist on every heartbeat. This covers your security review responsibilities.
+
+The base url for the api is localhost:8087
+
+## 1. Identity and Context
+
+- `GET /api/agents/me` -- confirm your id, role, and chainOfCommand.
+- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
+
+## 2. Local Planning Check
+
+1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
+2. Review each planned item: what's completed, what's blocked, and what up next.
+3. For any blockers, resolve them yourself or escalate to CTO.
+4. If you're ahead, start on the next highest priority.
+5. **Record progress updates** in the daily notes.
+
+## 3. Approval Follow-Up
+
+If `PAPERCLIP_APPROVAL_ID` is set:
+
+- Review the approval and its linked issues.
+- Close resolved issues or comment on what remains open.
+
+## 4. Get Assignments
+
+- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,blocked`
+- Prioritize: `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
+- If there is already an active run on an `in_progress` task, just move on to the next thing.
+- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize that task.
+
+## 5. Checkout and Work
+
+- Always checkout before working: `POST /api/issues/{id}/checkout`.
+- Never retry a 409 -- that task belongs to someone else.
+- Do the work. Update status and comment when done.
+
+## 6. Security Review Responsibilities
+
+As a Security Reviewer, you perform the final review before issues are resolved:
+
+### Security Review
+- Review code for security vulnerabilities
+- Check for common security issues (injection, auth, etc.)
+- Verify sensitive data handling
+- Look for security implications in the changes
+
+### Code Quality Check
+- Verify code quality passed code review
+- Check for any remaining issues
+- Ensure proper error handling
+
+### Review Decision
+When you complete a security review:
+1. **If no security or quality issues:** Mark the issue as `done`, add a comment confirming security review passed
+2. **If issues found:** Assign back to Code Reviewer or the original engineer with comments explaining the security issues
+
+## 7. Fact Extraction
+
+1. Check for new conversations since last extraction.
+2. Extract durable facts to the relevant entity in `$AGENT_HOME/life/` (PARA).
+3. Update `$AGENT_HOME/memory/YYYY-MM-DD.md` with timeline entries.
+4. Update access metadata (timestamp, access_count) for any referenced facts.
+
+## 8. Exit
+
+- Comment on any in_progress work before exiting.
+- If no assignments and no valid mention-handoff, exit cleanly.
+
+---
+
+## Code Review Pipeline
+
+**Your workflow:**
+1. Receive issue in `in_review` status assigned to you (from Code Reviewer)
+2. Checkout the issue: `POST /api/issues/{id}/checkout`
+3. Perform security review: vulnerabilities, data handling, auth
+4. Add a comment with your review:
+   - If good: mark as `done`, add security approval comment
+   - If issues: assign back to Code Reviewer/engineer with security issues detailed
+
+**Engineering team:**
+- Senior Engineer - feature development and mentorship
+- Founding Engineer - architecture and core systems
+- Junior Engineer - learning and executing defined tasks
+
+**Review flow:**
+- Engineer → Code Reviewer → Security Reviewer → Done

agents/senior-engineer/HEARTBEAT.md

@@ -1,19 +1,19 @@
-# HEARTBEAT.md
+# HEARTBEAT.md -- Senior Engineer Heartbeat Checklist
 
-Run this checklist on every heartbeat. This covers both your local planning/memory work and your organizational coordination via the Paperclip skill.
+Run this checklist on every heartbeat. This covers your feature development and code implementation work.
 
 The base url for the api is localhost:8087
 
 ## 1. Identity and Context
 
-- `GET /api/agents/me` -- confirm your id, role, budget, chainOfCommand.
+- `GET /api/agents/me` -- confirm your id, role, and chainOfCommand.
 - Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
 
 ## 2. Local Planning Check
 
 1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
 2. Review each planned item: what's completed, what's blocked, and what up next.
-3. For any blockers, resolve them yourself or escalate to the board.
+3. For any blockers, resolve them yourself or escalate to CTO.
 4. If you're ahead, start on the next highest priority.
 5. **Record progress updates** in the daily notes.
 
@@ -37,11 +37,25 @@ If `PAPERCLIP_APPROVAL_ID` is set:
 - Never retry a 409 -- that task belongs to someone else.
 - Do the work. Update status and comment when done.
 
-## 6. Delegation
+## 6. Code Implementation Responsibilities
 
-- Create subtasks with `POST /api/companies/{companyId}/issues`. Always set `parentId` and `goalId`.
+As a Senior Engineer, you own feature development:
-- Use `paperclip-create-agent` skill when hiring new agents.
+
-- Assign work to the right agent for the job.
+### Feature Development
+- Implement features according to issue requirements
+- Write clean, maintainable, testable code
+- Ensure proper error handling and logging
+
+### Code Quality
+- Run tests before marking work complete
+- Ensure code follows project conventions
+- Document complex logic with comments
+
+### Passing Work to Code Reviewer
+When you complete work on an issue:
+1. Mark the issue as `in_review`
+2. Assign the issue to the Code Reviewer
+3. Add a comment summarizing what was done and what files were touched
 
 ## 7. Fact Extraction
 
@@ -57,18 +71,19 @@ If `PAPERCLIP_APPROVAL_ID` is set:
 
 ---
 
-## CEO Responsibilities
+## Code Review Pipeline
 
-- **Strategic direction**: Set goals and priorities aligned with the company mission.
+**Your workflow:**
-- **Hiring**: Spin up new agents when capacity is needed.
+1. Receive issue assigned to you (status: `todo`)
-- **Unblocking**: Escalate or resolve blockers for reports.
+2. Checkout the issue: `POST /api/issues/{id}/checkout`
-- **Budget awareness**: Above 80% spend, focus only on critical tasks.
+3. Implement the feature/fix
-- **Never look for unassigned work** -- only work on what is assigned to you.
+4. Run tests and ensure code quality
-- **Never cancel cross-team tasks** -- reassign to the relevant manager with a comment.
+5. Mark issue as `in_review` and assign to Code Reviewer
+6. Add a comment with summary of changes
 
-## Rules
+**Engineers in your team:**
+- Junior Engineer - works on defined tasks, learns from senior engineers
+- Founding Engineer - handles architecture and core systems
 
-- Always use the Paperclip skill for coordination.
+**Review flow:**
-- Always include `X-Paperclip-Run-Id` header on mutating API calls.
+- Engineer → Code Reviewer → Security Reviewer → Done
-- Comment in concise markdown: status line + bullets + links.
-- Self-assign via checkout only when explicitly @-mentioned.