From dc71d5873b81aaf9effb94004ee8977c51d09079 Mon Sep 17 00:00:00 2001 From: Michael Chihlas Date: Fri, 1 May 2026 21:25:44 -0400 Subject: [PATCH] docs(ai): mark guides rewrite as merged in handoff and current task Update HANDOFF.md, CURRENT_TASK.md, and SESSION_LOG.md to reflect that PR #159 is being merged into main, replacing the in-flight "uncommitted" language with the merged-state rollup. Co-Authored-By: Claude Opus 4.7 (1M context) --- .ai/CURRENT_TASK.md | 2 +- .ai/HANDOFF.md | 36 +++++++++++++++--------------------- .ai/SESSION_LOG.md | 2 +- 3 files changed, 17 insertions(+), 23 deletions(-) diff --git a/.ai/CURRENT_TASK.md b/.ai/CURRENT_TASK.md index 6c60447e..5f31e71e 100644 --- a/.ai/CURRENT_TASK.md +++ b/.ai/CURRENT_TASK.md @@ -4,7 +4,7 @@ ## Recently shipped -- **2026-05-01 — In-product User Guides rewrite (uncommitted, on `main`).** Replaced 15 feature-dump guides with 43 problem-oriented Diátaxis how-tos grouped under 10 categories. Dropped Maintenance Flows / AI Assistant / Flow Assist Sparkles (UI no longer exists). Renamed Step Library → Solutions Library. Authored 14 net-new how-tos for FlowPilot-era surfaces (tasklane keyboard flow, what-we-know, resolve, escalate, record-fix-outcome, post-docs-to-ticket, share-update, pause-and-leave, build-script-from-scratch, open-suggested-flow, pin-a-flow, invite-teammate, etc.). Schema additions: `category`, optional `relatedSlugs`; hub renders category sections; detail page renders related-guides footer. Fixed rendering bug where `**bold**` in `step.tip` rendered literally. Killed misleading "N sections" subtitle on guide cards. Browser-verified against engineer + owner login (sidebar labels, account sub-pages, pilot-screen header buttons, Tasks panel, integration form). Two unverified items intentionally deferred: change-teammate-role (requires non-owner test member to inspect role-change control) and detailed Resolve / Escalate modal contents (Resolve gated by 6 pending tasks in test data). tsc and Vite build clean. +- **2026-05-02 — PR #159** In-product User Guides rewrite. Merged into `main`. Replaced 15 feature-dump guides with 43 problem-oriented Diátaxis how-tos grouped under 10 categories. Dropped Maintenance Flows / AI Assistant / Flow Assist Sparkles (UI no longer exists). Renamed Step Library → Solutions Library. Authored 14 net-new how-tos for FlowPilot-era surfaces (tasklane keyboard flow, what-we-know, resolve, escalate, record-fix-outcome, post-docs-to-ticket, share-update, pause-and-leave, build-script-from-scratch, open-suggested-flow, pin-a-flow, invite-teammate, etc.). Schema additions: `category`, optional `relatedSlugs`; hub renders category sections; detail page renders related-guides footer. Fixed rendering bug where `**bold**` in `step.tip` rendered literally. Killed misleading "N sections" subtitle on guide cards. Browser-verified against engineer + owner login (sidebar labels, account sub-pages, pilot-screen header buttons, Tasks panel, integration form). Two unverified items intentionally deferred: change-teammate-role (requires non-owner test member to inspect role-change control) and detailed Resolve / Escalate modal contents (Resolve gated by 6 pending tasks in test data). tsc and Vite build clean. - **2026-05-01 — PR #158** Session-screen UX impeccable pass + tasklane keyboard flow. Merged into `main` as `5e10005`. - **Impeccable pass** (5 sub-passes — distill / quieter / layout / typeset / polish): score 24/40 → 33/40. Removed the duplicate "Suggested checks" chip strip; added an inline `Next steps · N pending in Tasks` cue above the latest action-bearing AI bubble; consolidated the desktop session header to Resolve + Escalate + ⋯ kebab (Context / New Ticket / Update Ticket / Pause now under the kebab, mobile kebab gained Context + New Ticket parity); centered the messages column to `max-w-3xl` to match the composer; bubbles dropped to `rounded-xl`. Decoration sweep: dropped 3px side stripes (TaskLane done states, all 6 ProposalBanner modes, WhatWeKnowItem rows), gradient backgrounds (WhatWeKnow + every banner), accent borderTop on TaskLane header, backdrop-blur on handoff overlay, animate-pulse-amber ring in VerifyingBanner, bordered avatar boxes in banners. Type sweep: 14 distinct sizes → 5-step scale (10/11/12/13/14px). Icon disambiguation: `MessageCircleQuestion` split into `Pencil` (Answer CTA) + `HelpCircle` (per-check explainer). Dead `font-sans` audit (12 sites) and double `text-xs` cleanups. - **TaskLane keyboard-first flow** (real feature): Enter submits + auto-advances to next pending task, Shift+Enter newline, Esc cancels, focus jumps to Send Responses after the last submission. Mouse path also auto-advances. Subtle hint row teaches the shortcut. diff --git a/.ai/HANDOFF.md b/.ai/HANDOFF.md index 190768c7..131f3d63 100644 --- a/.ai/HANDOFF.md +++ b/.ai/HANDOFF.md @@ -2,41 +2,35 @@ # HANDOFF.md -**Last updated:** 2026-05-02 (post-guides-rewrite, uncommitted) +**Last updated:** 2026-05-02 (post-PR-159 — guides Diátaxis rewrite merged into `main`) -**Active task:** None. The guide rewrite is complete; working tree dirty pending review/commit. +**Active task:** None. Pick next from `.ai/TODO.md` or `03-DEVELOPMENT-ROADMAP.md`. + +**Just-merged:** PR #159 — In-product User Guides rewritten as 43 Diátaxis how-tos under 10 categories. Drops 3 deprecated guides, renames Step Library → Solutions Library, fixes tip-markdown rendering, adds 14 net-new how-tos for FlowPilot-era surfaces. ## Where this session ended -In-product User Guides at `/guides` rewritten from 15 feature-dump guides → 43 problem-oriented Diátaxis how-tos under 10 categories. Schema extended (`category`, `relatedSlugs`), hub re-rendered with category headings, detail page gained a Related guides footer, tip-markdown rendering bug fixed. All changes browser-verified (engineer + owner) against live UI, every detail page renders without 404, tsc clean. +PR #159 merged into `main`. CHANGELOG, CURRENT_TASK, SESSION_LOG all updated. See `.ai/CURRENT_TASK.md` "Recently shipped" for the structured rollup. -**Working tree dirty.** Files touched: -- `frontend/src/data/guides.ts` (full rewrite of `guides` array + new `categories` array + extended types) -- `frontend/src/pages/GuidesHubPage.tsx` (renders category sections, hides empty ones) -- `frontend/src/pages/GuideDetailPage.tsx` (related-guides footer, dropped section-count) -- `frontend/src/components/guides/GuideCard.tsx` (dropped section-count subtitle) -- `frontend/src/components/guides/GuideSection.tsx` (markdown bold now works in tips) -- `CHANGELOG.md` ([Unreleased] entry added) -- `.ai/CURRENT_TASK.md` ("Recently shipped" entry added) -- `.ai/SESSION_LOG.md` (session entry added) -- `.ai/HANDOFF.md` (this file) - -The user has not yet been asked to commit. When picking this up next session, check with the user before staging — they may want to ship as a single commit, branch + PR, or fold into another change in flight. +The 43 guides live at `/guides` in the app. Schema is now category-aware (`Guide.category`, optional `relatedSlugs`); `categories` const drives hub ordering. Browser-verified against engineer + owner test users (sidebar labels, account sub-pages, pilot-screen header buttons, Tasks panel, integration form). tsc and Vite build clean. ## Resume point — DO THIS NEXT -1. **Decide commit shape.** Likely a single commit on a `feat/guides-diataxis-rewrite` branch with PR. Pre-existing TODOs from the prior session (cleanup of #127, rewrite of #66, sections 3-5 of the issue cleanup plan) are **unblocked again** — pick up `2026-05-01-issue-cleanup-plan.md` section 3 (#58 structured "step is wrong" quality signals) once the guides land. +The issue cleanup plan continues from before this session. Pick up `docs/plans/2026-05-01-issue-cleanup-plan.md` at section 3: **#58 structured "step is wrong" quality signals**. Then section 4 (#60 recurring issue detection) and section 5 (#129 hierarchical guide navigation). -2. **Two follow-ups intentionally deferred from this session** (worth picking up if a related touch happens): - - **`change-teammate-role` how-to was dropped** because the test owner account has no non-owner members to inspect the role-change control. Once a teammate is invited via `invite-teammate`, verify whether the Membership list exposes a Role dropdown (or some other control) for non-owners and add the guide back. - - **Resolve / Escalate modal contents are unverified.** Browser couldn't drive Resolve to completion (test session has 6 pending Tasks gating it; clicking Resolve fired a toast). The how-tos point at the right buttons in the right place, but the exact modal copy and the Escalation Mode wedge specifics are based on project context, not live observation. Worth a quick spot-check the next time a clean test session is available. +`$GITEA_TOKEN` is in `.claude/settings.local.json` — confirmed working via the PR-creation API call this session. Issue tracker actions can be done from the code-server LXC via `curl` against `https://gitea.resolutionflow.com/api/v1/...`. -3. **`/etc/hosts` entry added on this code-server LXC.** `100.64.78.44 docker-01` — should now persist; HANDOFF.md previously claimed it was already there but wasn't. If `/browse` against `docker-01:5173` ever fails to resolve again, re-add it via `sudo tee` from a real terminal (the `!` shell prefix can't drive interactive sudo on this LXC). +## Followups deferred from this session + +Worth picking up if a related touch happens: + +- **`change-teammate-role` how-to was dropped** from PR #159 because the test owner account has no non-owner members to inspect the role-change control. Once a teammate is invited via the Membership form on `/account`, verify whether the list exposes a Role dropdown (or some other control) for non-owners and add the guide back to `frontend/src/data/guides.ts` under the `account-admin` category. +- **Resolve / Escalate modal contents are unverified.** Browser couldn't drive Resolve to completion (test session has 6 pending Tasks gating it; clicking Resolve fired a toast). The how-tos point at the right buttons in the right place, but the exact modal copy and the Escalation Mode wedge specifics are based on project context, not live observation. Worth a quick spot-check the next time a clean test session is available. ## Environment notes (carry-forward) - Code-server LXC has bun + docker but no native `python`/`node`/`npm`. Use `docker exec resolutionflow_{backend,frontend} …` for build/test commands. - No `gh` CLI on this LXC — use the Gitea API (`$GITEA_TOKEN`) for PR/issue work, or run `gh` from a host that has it. - Headless Chromium (`/qa`, `/browse`) needs `CONTAINER=1` in the env launching the browse server (LXC namespace constraint). -- `/etc/hosts` has `100.64.78.44 docker-01` so the headless browser resolves the bake-in `VITE_API_URL`. Confirmed persistent as of this session. +- `/etc/hosts` has `100.64.78.44 docker-01` so the headless browser resolves the bake-in `VITE_API_URL`. The previous handoff claimed this entry was persistent but it was missing on this LXC at the start of this session — re-added via `sudo tee` from a real terminal (the `!` shell prefix can't drive interactive sudo). Confirmed working. - Multi-head alembic state on `main` (heads `070`, `c0f3a4b7e91d`, `024`) is pre-existing. Use `alembic upgrade heads` (plural) if `head` complains. diff --git a/.ai/SESSION_LOG.md b/.ai/SESSION_LOG.md index 3fe5eee1..46cc9b22 100644 --- a/.ai/SESSION_LOG.md +++ b/.ai/SESSION_LOG.md @@ -12,7 +12,7 @@ --- -## 2026-05-02 ~01:00 UTC — Claude — In-product User Guides Diátaxis rewrite (uncommitted) +## 2026-05-02 ~01:00 UTC — Claude — In-product User Guides Diátaxis rewrite shipped (PR #159) - Audited the in-product `/guides` collection against live UI via `/browse` (engineer + owner test users). Existing 15 guides predated the FlowPilot pivot — every "click X in the sidebar" reference was wrong (Dashboard → Home, All Flows → Flows, Sessions → History, Exports gone, etc.). Three guides described surfaces that no longer exist: Maintenance Flows, AI Assistant page, Flow Assist Sparkles button. Findings written to `/tmp/guides-audit.md`. - Rebuilt `frontend/src/data/guides.ts` from scratch as 43 problem-oriented Diátaxis how-tos under 10 categories. Single-outcome each, terse imperative steps, real UI labels (Create New, Sign in, Manage, Build New Script, Send Invite, Save Settings, Create Category, etc.). Added `category: CategoryId` and optional `relatedSlugs?: string[]` to the `Guide` interface; new `Category` type and `categories` const drive the hub layout. `GuidesHubPage` now renders category sections (auto-hides empty); `GuideDetailPage` renders a Related guides footer; `GuideCard` lost its misleading "N sections" subtitle.