wip(handoff): clean stale TODOs and plan issue cleanup

Co-Authored-By: Codex <noreply@openai.com>

.ai/HANDOFF.md

@@ -2,24 +2,23 @@
 
 # HANDOFF.md
 
-**Last updated:** 2026-05-01 (session 7 — backlog/Gitea issue validity audit)
+**Last updated:** 2026-05-01 (session 8 — cleaned stale TODOs, wrote issue cleanup plan)
 
 **Active task:** None. Pick next from `.ai/TODO.md` or roadmap.
 
-**Just-reviewed:** `.ai/TODO.md`, inline code TODOs, and open Gitea issues were checked against current `main`.
+**Just-updated:** stale local TODOs were removed and an issue cleanup plan was added.
 
 ## Where this session ended
 
-Review-only audit completed; no source code changes were needed. Key findings:
+Cleanup follow-up completed:
 
-- `.ai/TODO.md`: pytest-xdist item is stale/resolved; lint cleanup is still valid but now 24 warnings, not 23; selector hardening, ResourceWarning filter audit, transactional rollback, testmon, `currentChatRef` observability, peer-tech escalation, and Escalation Mode mobile follow-up are still valid.
+- `.ai/TODO.md`: removed resolved pytest-xdist "Up next" item, removed resolved claim-role-gate item, updated frontend lint count to 24 warnings.
-- Gitea open issues: #58, #60, #128, #129, #130 are still valid. #66 is partially resolved by `.rfflow` export/import; only template packs/marketplace remain. #127 is mostly resolved by assistant empty-state copy plus prompt boundaries; close or rewrite if an always-visible badge is still desired.
+- Added `docs/plans/2026-05-01-issue-cleanup-plan.md` with tracker hygiene and implementation order.
-- Open Gitea PR #124 (`feat/cockpit-harness`) is stale/unmergeable against current `main` and overlaps/supersedes newer `/pilot` work.
+- Tried to close Gitea #127 via API, but this environment has no Gitea token; API returned `401 token is required`.
-- Inline TODOs still valid: post-session feedback prompt, FlowPilot analytics domain/time-entry TODOs, prompt-cache verification note unless live `anthropic.cache` evidence is confirmed, `ProposalDetail` modify-on-editor-save, and procedural ghost-step accept/dismiss handlers.
 
 ## Resume point — DO THIS NEXT
 
-Pick a still-valid task from the audit above. Highest cleanup leverage: remove/update stale TODO/Gitea items before implementing new work, especially `.ai/TODO.md` xdist and Gitea #66/#127.
+If tracker auth is available, close #127 and close/archive stale PR #124; rewrite #66 to template packs / one-click install only. Then pick from the plan: low-risk maintenance first, then #130/#128 pilot UX friction.
 
 ## Environment notes (carry-forward)
 

.ai/SESSION_LOG.md

@@ -12,6 +12,15 @@
 
 ---
 
+## 2026-05-01 06:05 UTC — Codex — Clean stale TODOs and add issue cleanup plan
+
+- Removed the resolved pytest-xdist item from `.ai/TODO.md` and reset "Up next" to no selected task.
+- Removed the resolved "Add role gate to handoff claim endpoint" backlog item from `.ai/TODO.md`.
+- Updated the frontend lint cleanup TODO from 23 warnings to the current `npm run lint` result: 24 warnings, 0 errors.
+- Tried to close Gitea #127 through the API, but this environment has no Gitea token; API returned `401 token is required`.
+- Added `docs/plans/2026-05-01-issue-cleanup-plan.md` with safe tracker actions and a recommended order for clearing remaining issues.
+- Files touched: `.ai/TODO.md`, `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md`, `docs/plans/2026-05-01-issue-cleanup-plan.md`.
+
 ## 2026-05-01 05:40 UTC — Codex — Audit TODO backlog and Gitea issue validity
 
 - Compared `.ai/TODO.md`, inline code TODOs, and open Gitea issues against current `main`.

.ai/TODO.md

@@ -5,11 +5,11 @@
 
 ## Up next
 
-- [ ] **Parallelize backend pytest with pytest-xdist.** ✅ landing as PR #151. Verified locally: backend suite 22 min → 4m 28s with `-n auto` on the 8-core homelab runner. Per-worker DB isolation via `PYTEST_XDIST_WORKER` in conftest.py.
+None selected. Pick from the backlog below or `03-DEVELOPMENT-ROADMAP.md`.
 
 ## Backlog
 
-- [ ] **Frontend lint warnings cleanup.** 23 `react-hooks/exhaustive-deps` warnings remain after PR #149 (mostly missing-deps in useEffect). Either fix them or audit them for known-safe ones and add eslint-disable comments. Not blocking CI today.
+- [ ] **Frontend lint warnings cleanup.** `npm run lint` currently reports 24 warnings (0 errors): mostly `react-hooks/exhaustive-deps` plus a few unused eslint-disable directives. Either fix them or audit known-safe ones and add/remove eslint-disable comments intentionally. Not blocking CI today.
 - [ ] **Audit `filterwarnings` ignores added in `wip(handoff): restore backend suite to green`.** Codex added narrow `ResourceWarning` filters for unclosed socket/transport/event-loop noise from pytest-asyncio teardown. Worth periodically reviewing whether those are still needed (e.g. when bumping pytest-asyncio) — if a real warning appears in those forms it would be silenced.
 - [ ] **Add `data-testid` attributes to e2e-critical interactive elements.** PR #152 fixed five Playwright tests by chasing UI-text changes (`Sessions` → `Session History`, `Account Settings` → `Account Management`, `/assistant` → `/pilot`, "Flow Sessions" tab, Resume button on session cards). Each was a one-line selector update, but every UI churn re-breaks them. Adding stable `data-testid` attributes on the targeted elements (page heading wrappers, tab nav, primary action buttons) and switching tests to `getByTestId` would make these immune to copy/route renames. Scope it small — start with `SessionHistoryPage` heading, the AI/Flow Sessions tab buttons, the per-session `Resume` button, and the command-palette FlowPilot option.
 - [ ] **Per-test transactional rollback in `test_db` fixture.** Bigger engineering than xdist (which we already shipped). Instead of `DROP SCHEMA public CASCADE` per test, wrap each test in a savepoint and rollback at teardown. ~30-40% additional speedup on top of xdist for test-DB-heavy tests. Real refactor; only worth it if the suite gets significantly larger or runs more frequently.
@@ -19,5 +19,3 @@
 - [ ] **Allow peer-tech to escalate a colleague's session.** Today `POST /ai-sessions/{session_id}/handoff` in [endpoints/session_handoffs.py:48](backend/app/api/endpoints/session_handoffs.py#L48) filters by `AISession.user_id == current_user.id`, so only the session owner can escalate. Real MSP shops have peer hand-offs: Junior A is on lunch, Junior B sees the session is stuck and should be able to escalate it. Auth tweak: switch from session-owner check to `require_engineer_or_admin` + same-account scope. Add a `handed_off_by` audit column (already exists on `SessionHandoff`) so the original-owner-vs-actual-escalator distinction is preserved. Surfaced from /plan-eng-review on the Escalation-Mode wedge plan; v1 wedge demo doesn't need this (solo-founder pilot), but capture for v2 once 3+ pilots are live and a peer-claim need surfaces.
 
 - [ ] **Mobile/responsive design for EscalationQueue + handoff-context screen.** Pre-PMF wedge demo targets desktop only — MSP techs work on laptops/desktops in shop environments. Once 3+ paying customers exist and a tech requests mobile (likely on-call use case), spec the responsive behavior: stacked card layout below `sm:` breakpoint, full-bleed handoff-context overlay on mobile, swipe-to-claim gesture instead of Pick Up button. Surfaced from /plan-design-review on the Escalation-Mode wedge plan.
-
-- [ ] **(MOVED IN-SCOPE for Escalation Mode v1, 2026-04-27)** ~~Add role gate to handoff claim endpoint.~~ Codex review correctly flagged this as wedge-relevant (the race-condition story depends on auth gating). Now part of the Escalation Mode v1 build, not a deferred TODO.

docs/plans/2026-05-01-issue-cleanup-plan.md

@@ -0,0 +1,74 @@
+# Issue Cleanup Plan - 2026-05-01
+
+## Tracker Hygiene
+
+These are safe tracker updates before any feature work:
+
+1. Close Gitea #127 (`feat: show AI content scope indicator`) unless an always-visible badge is still desired.
+   - Current code already has IT/MSP scope copy in the assistant empty state.
+   - `ASSISTANT_SYSTEM_PROMPT` also has an off-domain redirect boundary.
+2. Rewrite Gitea #66 (`Tree Templates + Import/Export`) to the remaining scope only.
+   - `.rfflow` export/import is implemented in `tree_transfer.py` and exposed in the library UI.
+   - Remaining work: curated packs, authenticated one-click install from gallery, template versioning, marketplace/community path.
+3. Close or archive open PR #124 (`feat/cockpit-harness`).
+   - It is unmergeable against current `main` and overlaps newer `/pilot` work.
+4. Keep Gitea #58, #60, #128, #129, #130 open.
+   - They still describe real product gaps.
+
+## Recommended Order
+
+### 1. Low-Risk Maintenance
+
+- Clean frontend lint warnings.
+- Audit/remove stale eslint-disable comments.
+- Add missing `data-testid` selectors for e2e-critical controls.
+- Add observability around unexpected `currentChatRef` guard mismatches.
+
+Why first: these reduce future regression cost and are small, well-bounded changes.
+
+### 2. Pilot UX Friction
+
+- #130: Add diagnostic command help affordances in `TaskLane` / action cards.
+- #128: Decide whether task panel placement should be configurable or whether the existing responsive drawer is enough.
+- EscalationQueue mobile design stays deferred until a customer asks for it.
+
+Why second: this improves the current FlowPilot wedge without changing core data models.
+
+### 3. Workflow Quality Signals
+
+- #58: Add structured "step is wrong" flags separate from thumbs-up/down helpfulness.
+- Existing `StepFeedback` is not enough; it only records helpful/unhelpful and cannot capture incorrect/outdated/unclear/missing-info reasons.
+
+Why third: useful, but needs schema/API/UI/admin surfaces.
+
+### 4. Client Intelligence
+
+- #60: Recurring issue detection.
+- Start with a read-only banner using existing `sessions.client_name + tree_id` filters.
+- Add same-resolution detection only after confirming the available session outcome/node data is reliable enough.
+
+Why fourth: high value, but it touches session-start and close-out flows and needs careful false-positive handling.
+
+### 5. Documentation Structure
+
+- #129: Hierarchical guide navigation.
+- Current `/guides` route is a card grid plus detail pages with sections and breadcrumbs, but not a collapsible guide tree.
+
+Why fifth: valid UX request, but less urgent than pilot workflow gaps.
+
+## Gitea Actions Needed
+
+The current environment does not have a Gitea token configured, so API writes fail with `401 token is required`. Once authenticated:
+
+```bash
+curl -X PATCH \
+  https://gitea.resolutionflow.com/api/v1/repos/chihlasm/resolutionflow/issues/127 \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"state":"closed"}'
+```
+
+For #66, prefer editing the title/body instead of closing it:
+
+- Title: `feat: curated template packs and one-click install`
+- Body: remove completed `.rfflow` export/import acceptance criteria and keep pack/install/versioning work.