roboco/docs/bugs/backend/pr769-route-helper-extraction-regression.md

# Route-Helper-Extraction Refactor Silently Dropped Product Code (PR #769/#772)

## Description

An earlier route-helper-extraction refactor (Batch A task `4baffaa3`, Batch B task
`f8480831`) moved helper functions out of route files into their proper service-layer
modules per the Architectural Conventions Standard. During that extraction, the branch
silently **dropped**, rather than relocated, a substantial slice of pre-existing product
behavior. The follow-up PR (#769, later reopened as #772) bounced `needs_revision` twice
on `pr_gate` findings before the cause was correctly diagnosed: `sync_branch` on the
subtask returned `head==base tip` (no drift) both times, ruling out branch staleness and
confirming the content was genuinely missing from the branch, not just out of sync with
`main`.

## Root Cause

The extraction commit(s) removed the following without a corresponding relocation, each
verified against real call sites that would `NameError`/`AttributeError` at runtime:

- **`roboco/services/task.py`**: ~22 public `TaskService` methods — all 12
  `list_open_*_cycles` board-program queries, `list_sentinel_reports`,
  `list_periscope_briefs`, `sequence_hold_reason`, `task_spend_usd`,
  `project_month_spend_usd`, `terminal_children_count`, `self_heal_ac_ids`,
  `resolve_scales_task_ref`, `list_open_env_sync_tasks`, `_close_task_pr_best_effort`,
  `_inherit_upstream_base`, `list_completed_coroner_postmortems`, and the module-level
  `_fire_coroner_bounce_hook` plus its sibling `_fire_coroner_cancel_hook_if_work_started`.
  Callers spanned `coroner.py`, `sentinel.py`, `periscope.py`, `project.py`,
  `coroner_engine.py`, `content_actions.py`, `choreographer/_impl.py`, `orchestrator.py`,
  and every `*_engine.py` site calling a `list_open_*_cycles` method.
- **`roboco/services/video_engine.py`**: `reauthor_from_rejection`,
  `_open_video_task_locked`, `_resolve_reauthor_project`, plus supporting occasion-lock /
  AC scene-criterion / product-name-resolution code `test_video_engine.py` depends on.
- **`roboco/services/video_post_service.py`**: `_platform_configured`,
  `_reauthor_after_reject`, plus a CANCELLED-draft `approve()` guard and the
  unconfigured-platform-skip behavior `test_video_post_service.py` requires.
- **`roboco/services/a2a.py`**: `_maybe_wake_ceo_recipient`,
  `_ack_pending_wake_notifications` (the CEO-DM-wake path wired into `send_chat_message` /
  `interject_as_ceo` / `get_unread_messages`).
- **25 tests** deleted with zero replacements in `test_video_routes.py`,
  `test_tasks_routes.py`, `test_orchestrator_manual_spawn.py`, including
  security-relevant coverage: symlink-traversal confinement, non-CEO-forbidden checks,
  agent-id-traversal rejection, `budget_usd` validation.

## Solution Implemented

Every named method, hook, and test was reconstructed against its real callers and
pre-existing test expectations (not guessed) and restored in the same modules the
extraction had emptied them from:

- All ~22 `task.py` methods restored, including wiring `self_heal_ac_ids` into
  `_parent_ac_ref_sets` so the AC-coverage digest self-heals a legacy/drifted parent
  instead of staying permanently inert, and wiring the Coroner bounce hook
  (`CORONER_BOUNCE_THRESHOLD = 3`) into `_emit_status_transition_audit`'s
  revision-count-bump branch via a new `_schedule_coroner_bounce_hook` helper (kept
  separate so the scheduling try/except doesn't inflate that chokepoint's own
  complexity), plus the sibling `_fire_coroner_cancel_hook_if_work_started` into
  `cancel()`.
- `video_engine.py` / `video_post_service.py` / `a2a.py` methods restored with their
  supporting code, verified directly against each file's existing test suite.
- The 25 deleted tests restored, including the named security-relevant cases
  (`test_validated_agent_id_still_rejects_traversal`, symlink confinement,
  non-CEO-forbidden, `budget_usd` validation); pause/resume coverage in
  `test_tasks_routes.py` was confirmed already intact and not actually missing.
- `_finalize_claim`'s upstream-base-inherit condition was extracted into a pure
  `_should_inherit_upstream_base` helper: restoring the Coroner hooks pushed
  `_emit_status_transition_audit` / `cancel()` / `_finalize_claim` over the xenon
  complexity budget, so all three were brought back under threshold with identical
  behavior.

**Explicitly out of scope, left untouched:** `board_programs.py`, `coroner.py`,
`dogfood.py`, `github_app.py`, `mirror.py`, `periscope.py`, `pest_control.py`,
`scales.py`, `sentinel.py`, `spackle.py`, `telegram.py` route files — none are named in
the parent task's (`d41bbbf5`) file-enumeration scope. Their own unrelated
helper-placement findings were confirmed as a separate, later architectural-drift
surface and were not pulled into this diff.

## Impact

- **Scope:** Restoration only — no new product behavior beyond re-wiring the Coroner
  bounce/cancel hooks the extraction had silently dropped (that wiring was already
  documented at the architecture level in `CLAUDE.md`'s Board Program registry as "wired
  at TaskService's bounce/cancel chokepoints"; this PR is what makes that description
  true again on disk).
- **Risk:** The 27+ real call sites named above would have raised
  `NameError`/`AttributeError` at runtime had this shipped un-restored, and 3
  security-relevant test cases would have stayed uncovered.
- **Verification:** `mypy roboco/ tests/` clean (0 errors across 1438 files); `ruff
  format`/`check` clean; xenon complexity clean; the 3 originally-flagged test files
  plus `test_coroner_hooks.py` pass against a live sandbox Postgres (281+ tests); the
  full 656-test targeted regression suite passes with no new failures.

## Prevention Measures

A **placement-only** refactor (moving a definition to satisfy the Architectural
Conventions Standard) must be diffed against its source branch for **deletions**, not
just additions, before it is called done — `git diff --stat` on the refactor branch vs.
its base, or a simple count of `def ` occurrences per touched file pre/post, would have
caught this class of silent drop immediately. When a `pr_gate` finding claims code is
"missing" post-refactor, verify with `sync_branch` (or an equivalent stale-vs-real
check) before assuming the finding is a false-positive staleness artifact — in this
case the branch was never stale; the code was actually gone.