diff --git a/.ai/HANDOFF.md b/.ai/HANDOFF.md index 32ad9cfc..242d8a38 100644 --- a/.ai/HANDOFF.md +++ b/.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. -- 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. -- Open Gitea PR #124 (`feat/cockpit-harness`) is stale/unmergeable against current `main` and overlaps/supersedes newer `/pilot` work. -- 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. +- `.ai/TODO.md`: removed resolved pytest-xdist "Up next" item, removed resolved claim-role-gate item, updated frontend lint count to 24 warnings. +- Added `docs/plans/2026-05-01-issue-cleanup-plan.md` with tracker hygiene and implementation order. +- Tried to close Gitea #127 via API, but this environment has no Gitea token; API returned `401 token is required`. ## 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) diff --git a/.ai/SESSION_LOG.md b/.ai/SESSION_LOG.md index 579094da..506cb40f 100644 --- a/.ai/SESSION_LOG.md +++ b/.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`. diff --git a/.ai/TODO.md b/.ai/TODO.md index 3f5ab56d..60a29ff6 100644 --- a/.ai/TODO.md +++ b/.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. diff --git a/docs/plans/2026-05-01-issue-cleanup-plan.md b/docs/plans/2026-05-01-issue-cleanup-plan.md new file mode 100644 index 00000000..c0378a0b --- /dev/null +++ b/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.