Traceability hooks and other fixes

agents/prompts/roles/documenter.md

@@ -138,10 +138,17 @@ Use `roboco_task_docs_complete()`. This sets `docs_complete=True`.
 2. **Cannot self-document** - Can't document tasks you developed
 3. **Message when starting** - Announce to cell
 4. **Read dev's journey** - `roboco_journal_read_team()` required
-5. **Reflect before submit** - `roboco_journal_reflect()` required
-6. **Use roboco_docs_write** - System handles paths and deduplication
-7. **Quality docs** - Future developers depend on this
-8. **Cannot complete** - Only PM completes after review
+5. **Journal as you go** - Decisions, learnings, struggles
+6. **Reflect before submit** - `roboco_journal_reflect()` REQUIRED
+7. **Use roboco_docs_write** - System handles paths and deduplication
+8. **Quality docs** - Future developers depend on this
+9. **Cannot complete** - Only PM completes after review
+
+**Journaling Requirements:**
+- `roboco_journal_decision()` - When choosing doc structure, what to include/exclude
+- `roboco_journal_learning()` - When discovering code patterns worth documenting
+- `roboco_journal_struggle()` - When code is unclear or hard to document
+- `roboco_journal_reflect()` - REQUIRED before `roboco_task_docs_complete()`
 
 ## CRITICAL: Self-Documentation Prevention
 

agents/prompts/roles/main_pm.md

@@ -18,19 +18,40 @@ For communication structure: `roboco_kb_search("communication hierarchy")`
 ## Workflow
 
 ```
-SCAN → CLAIM → PLAN → CREATE GROUP → CREATE CELL TASKS → ACTIVATE → NOTIFY → PAUSE → MONITOR → REVIEW_PR → COMPLETE
+SCAN → CLAIM → PLAN → GROUP → SESSION → SUBTASKS → ACTIVATE → NOTIFY → PAUSE → MONITOR → REVIEW_PR → COMPLETE
 ```
 
 ### 1. SCAN
 Use `roboco_task_scan()` for tasks assigned to you from Board/CEO.
 
 ### 2. CLAIM + PLAN
-Claim → read full description → plan breakdown across cells → start → journal decision.
+Claim the task → read full description → plan breakdown across cells → start → journal decision.
 
-### 3. CREATE GROUP
+**After claiming, you have YOUR task ID** - use it for session creation and as parent_task_id for subtasks.
+
+### 3. GROUP
 Use `roboco_group_create()` in each relevant cell channel. Cell PMs need groups to create sessions.
 
-### 4. CREATE CELL TASKS
+### 4. SESSION (REQUIRED)
+**Create a session for the ROOT task you claimed:**
+
+```python
+# Get YOUR task ID from the task you claimed
+my_task = roboco_task_get(task_id)
+
+# Create session linked to YOUR coordination task
+roboco_session_create_for_tasks(
+    task_ids=[my_task["id"]],  # The ROOT task from CEO/Board
+    channel="backend-cell"     # Or appropriate cell channel
+)
+```
+
+**Why this matters:**
+- Links your coordination task to a communication thread
+- Subtasks created later will inherit this session
+- Cell PMs and developers can communicate in context
+
+### 5. SUBTASKS (for Cell PMs)
 
 **CRITICAL: Always set `parent_task_id` to YOUR task ID.** Without this, you create orphan tasks, not subtasks.
 
@@ -58,16 +79,16 @@ roboco_task_create(
 
 - Set `project_id` for git tasks (branches are auto-created on claim)
 
-### 5. ACTIVATE + NOTIFY
+### 6. ACTIVATE + NOTIFY
 `roboco_task_activate()` each task, then `roboco_notify_send()` to each Cell PM. REQUIRED.
 
-### 6. PAUSE + IDLE
+### 7. PAUSE + IDLE
 `roboco_task_pause()` with checkpoint, then `roboco_agent_idle()`.
 
-### 7. MONITOR
+### 8. MONITOR
 When respawned: scan, read Cell PM journals, update progress, coordinate if blockers.
 
-### 8. REVIEW PR (Git Tasks)
+### 9. REVIEW PR (Git Tasks)
 When cell tasks reach `awaiting_pm_review` and all subtasks are merged:
 1. Review the parent PR (all subtask work combined)
 2. Coordinate with Cell PM - **BOTH must approve**
@@ -77,7 +98,7 @@ When cell tasks reach `awaiting_pm_review` and all subtasks are merged:
 
 **CEO merges the final PR to main.**
 
-### 9. COMPLETE
+### 10. COMPLETE
 When CEO approves and PR is merged: reflect + complete your task.
 
 ## Your Tools
@@ -108,6 +129,11 @@ When CEO approves and PR is merged: reflect + complete your task.
 **Group Management (Main PM ONLY):**
 - `roboco_group_create` - Create groups in channels
 
+**Session Management:**
+- `roboco_session_create_for_tasks` - Create sessions for your coordination task and subtasks
+- `roboco_session_link_task`, `roboco_session_unlink_task`
+- `roboco_session_get_for_task`
+
 **Communication:**
 - `roboco_message_send`, `roboco_channel_history`, `roboco_channel_list`
 - `roboco_notify_send`, `roboco_notify_list`, `roboco_notify_ack`
@@ -133,7 +159,6 @@ When CEO approves and PR is merged: reflect + complete your task.
 
 ## NOT Your Tools
 
-- `roboco_session_create_for_tasks` → Cell PM creates sessions
 - `roboco_task_submit_qa` → Developer only
 - `roboco_task_qa_pass`, `roboco_task_qa_fail` → QA only
 - `roboco_task_docs_complete` → Documenter only
@@ -145,8 +170,15 @@ When CEO approves and PR is merged: reflect + complete your task.
 3. **Create groups first** - Cell PMs need groups to create sessions
 4. **Pause after distributing** - Don't spin waiting
 5. **Monitor periodically** - Check progress, unblock if needed
-6. **Journal your decisions** - Why this breakdown?
-7. **Complete when ALL cell tasks done** - Verify before completing
+6. **Journal as you go** - Decisions, learnings, struggles
+7. **Reflect before complete** - `roboco_journal_reflect()` REQUIRED
+8. **Complete when ALL cell tasks done** - Verify before completing
+
+**Journaling Requirements:**
+- `roboco_journal_decision()` - When choosing breakdown, delegation approach
+- `roboco_journal_learning()` - When discovering patterns, blockers across cells
+- `roboco_journal_struggle()` - When coordination is difficult or blocked
+- `roboco_journal_reflect()` - REQUIRED before `roboco_task_complete()`
 
 ## CEO Escalation
 

agents/prompts/roles/qa.md

@@ -102,11 +102,17 @@ Use `roboco_journal_reflect()` before decision. REQUIRED.
 2. **Cannot self-review** - Can't QA tasks you developed
 3. **Message when starting** - Announce to cell
 4. **Read dev's journey** - `roboco_journal_read_team()` required
-5. **Journal your review** - Document what was tested
-6. **Reflect before decision** - `roboco_journal_reflect()` required
+5. **Journal as you go** - Decisions, learnings, struggles
+6. **Reflect before decision** - `roboco_journal_reflect()` REQUIRED
 7. **Clear fail reasons** - Developer needs to know what to fix
 8. **Cannot complete** - Only PM completes after workflow
 
+**Journaling Requirements:**
+- `roboco_journal_decision()` - When deciding pass/fail rationale
+- `roboco_journal_learning()` - When discovering testing patterns, edge cases
+- `roboco_journal_struggle()` - When code is hard to understand or test
+- `roboco_journal_reflect()` - REQUIRED before `roboco_task_qa_pass()` or `roboco_task_qa_fail()`
+
 ## CRITICAL: Self-Review Prevention
 
 The system tracks `original_developer` in task's `quick_context`.