Replace 15 feature-dump guides with 43 problem-oriented how-tos grouped
under 10 categories. Drop Maintenance Flows / AI Assistant / Flow Assist
Sparkles — those surfaces no longer exist post-FlowPilot pivot. Rename
Step Library → Solutions Library throughout. Correct every "click X in
the sidebar" reference to match live labels (Home, History, Tickets,
Flows, Scripts, Data, Acct).
Schema: add `category: CategoryId` and optional `relatedSlugs` to Guide;
new Category type and `categories` const drive hub ordering. GuidesHubPage
renders category sections (auto-hides empty); GuideDetailPage renders a
related-guides footer when set; GuideCard drops the misleading "N sections"
subtitle.
Fix step.tip markdown rendering — `**bold**` rendered literally because
tip used plain text instead of the same regex replacement used on
instruction.
14 net-new how-tos for FlowPilot-era surfaces with no prior coverage:
tasklane keyboard flow, view-what-we-know, ask-AI mid-session,
pause-and-leave, resolve, record-fix-outcome, escalate (Escalation
Mode), post-docs-to-ticket, send-client-update, build-script-from-scratch,
open-suggested-flow, pin-a-flow, invite-teammate.
Browser-verified against engineer + owner test users (sidebar labels,
account sub-pages, pilot-screen header buttons, Tasks panel, integration
form). tsc clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Updates the .ai/ handoff trio after PR #156 merge:
- CURRENT_TASK.md: clear active task; record #156 in Recently shipped
alongside #155 with one-line summary and QA-report pointer.
- HANDOFF.md: rewrite resume point as "pick next from TODO/roadmap";
document carry-forward env quirks (CONTAINER=1 for Chromium,
docker-01 hosts entry, multi-head alembic state).
- SESSION_LOG.md: append session entry for QA + merge.
Also includes the .gstack/qa-reports/ artifacts (report + 8 screenshots).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Page-level Resolve patches applied_pending → applied_success before
opening the resolution flow, so resolved sessions don't carry a
provisional pending fix.
- Page-level Escalate intercept now catches applied_pending in addition
to verifying/partial; intercept copy generalized from "Verifying state"
to "still needs an outcome."
- PendingBanner gains a Dismiss action, matching the PR body and the
backend's allowed pending → dismissed transition.
- resolution_note_generator and escalation_package_generator system
prompts no longer include real-looking pending examples (anti-parrot
guardrail compliance).
Verified via Docker: prompt anti-parrot 2/2, suggested-fix outcome suite
21/21, frontend tsc -b clean, npm run build clean.
Co-Authored-By: Codex <noreply@openai.com>
Closes out Escalation Mode (PR #155 merged) and pivots active task to
the new applied_pending suggested-fix outcome on PR #156.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Codex review pass on the escalation wedge. Reworks claim_session from
read-then-write to a conditional UPDATE so two seniors racing can't both
win, blocks the original engineer from claiming their own handoff, and
filters self-escalated sessions out of the dashboard escalation queue.
Also preassigns the handoff UUID before flush so the compatibility
escalation_package payload carries it. Removes legacy frontend pickup
state (claiming, handleStartHere) that broke tsc --noEmit.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- HANDOFF: rewritten resume point. AI summary blocker is the active
task; consolidation plan is the path. 5-step implementation order
with watch-outs and breadcrumbs.
- CURRENT_TASK: updated commit table through 0d1b305. Documents the
live-test results (what works, the AI summary blocker), full
consolidation design with proposed payload shape.
- SESSION_LOG: chronological entry covering live QA bash, two
pickup bugs found + fixed, the three Enter/dashboard/timeout
fixes, and the architectural smell that surfaced.
- DECISIONS: new entry "Consolidate the three per-escalation AI
calls into one structured generation" — rejected alternatives
(bump timeout further, copy status-update content the wrong way,
switch to Haiku) and consequences (5s magic-moment, ~60% token
reduction, instant Ticket Notes button, schema enforcement
required, migration concerns documented).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- HANDOFF: rewritten resume point. First action on resume is `git push`
(commits 0f00ee5 and 665530f are local-only). Visual QA + bug bash is
the active work; 4 plan-locked items + the structural task-lane fix
all need real-browser verification.
- CURRENT_TASK: add 0f00ee5 and 665530f to the commit table; reframe
"Just shipped" as a per-commit summary; flag the task-lane fix as
needing visual confirmation.
- SESSION_LOG: chronological entry for this session with full detail
(audit, four polish items, race-condition wiring, structural
task-lane fix, test status, files touched).
- DECISIONS: new entry "Tag the task-lane state with an owner chatId"
documenting the structural pattern, what was rejected, and the
forward implication that future task-lane state slices follow the
same owner-tagging pattern.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Four items from the design-plan audit, all flagged as locked-design or
Codex corrections, shipped together so the GTM demo path covers them
end-to-end before bug bash.
1. Live AI assessment refresh on the magic-moment screen. Backend already
publishes handoff_assessment_ready when enrich_escalation_async commits;
wire the frontend listener so the senior sees the assessment populate
without a manual reopen. New event type + onAssessmentReady handler on
streamEscalations; AssistantChatPage opens a scoped SSE subscription
whenever it tracks a handoff missing its assessment, refetches on match,
and replaces magicHandoff / overlayHandoff in place. Closes the loop on
the async-assessment commit e8ba74e.
2. Suggested-step chips below the chat input. Locked design from the plan
(Codex correction). Chip strip renders above the composer post-claim
when ai_assessment_data.suggested_steps[] is non-empty. Click prefills
the input and focuses; first send or explicit X hides for the session.
3. Unread 6px dot on EscalationQueue cards. localStorage-persisted seen
set (rf-escalation-seen, capped 200). Dot top-right when not seen.
Cleared on open (card click) or claim (Pick Up) — NOT on hover, per
Codex correction. Pick Up stops propagation so it doesn't double-fire.
4. Race-condition toast on claim conflict. The /claim endpoint previously
silently overwrote claimed_by — both seniors thought they owned the
session. New HandoffAlreadyClaimedError carries the winner's id/name/
timestamp; claim_session rejects different-user re-claims (same-user is
idempotent for double-click safety); endpoint returns 409 with
structured detail. AssistantChatPage.handleStartHere extracts and
surfaces "Already claimed by {name} {time_ago}." via toast, drops
?pickup=true, dismisses magic-moment so the loser flows back to queue.
Tests: 2 new unit tests in test_handoff_manager.py (conflict raises,
same-user idempotent). Full handoff + escalation suite (34 tests) green.
Frontend tsc -b clean.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Records 029680a — every escalation now funnels through HandoffManager
regardless of which URL it entered through, so /escalate from
EscalateModal produces the full set of artifacts (handoff row,
AppNotification, SSE event, Slack/Teams via notify, per-user emails,
documentation, PSA push) and the bell-icon notification opens the
magic-moment screen end-to-end. Notes the legacy SessionBriefing branch
+ flowpilot_engine.escalate_session as orphaned, scheduled for removal
after pilots have run a couple of weeks on the unified path.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Updates the handoff trio after the legacy notification flow fix and
the branch push. PR #155 is open against main as draft. Resume point
is now visual QA via /qa, then deferred follow-ups (chat-input
suggested-step chips, snapshot expansion). Logs the open question
about whether EscalateModal should switch to /handoff.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Marks the magic-moment handoff-context screen as shipped, points the
next session at visual QA + push + draft PR, and captures the deferred
follow-ups (suggested-step chips, snapshot expansion, toolbar button
on revisits, owner analytics, Playwright e2e).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Marks the SSE subscription as shipped, points the next-session resume
target at the magic-moment handoff-context screen, and logs the live
end-to-end verification.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Default Claude Code model is being switched from Opus 4.7 1M-context to
Opus 4.7 (200k). Tighten the per-session pickup docs so they're
self-sufficient under the smaller window:
- CURRENT_TASK now reflects the post-Codex state: 8 commits on the
branch (5 feat + WIP SSE + 2 Codex test/latency fixes + 1 doc
refresh), 32/32 backend tests with -n auto, frontend tsc -b clean.
Remaining work re-scoped: the SSE backend half is feature-complete
and tested, so what's left is the FRONTEND SSE subscription in
EscalationQueue.tsx, then the magic-moment handoff-context screen,
then push + draft PR.
- Session log gets a Claude Code entry covering today's planning →
build → pause-for-Codex arc, the design decisions locked into the
doc and code, the two TODOs added (peer-tech escalation, mobile
responsive), and the model-switch context for the next session.
- HANDOFF.md needs no change — Codex's update in 9bdd995 already
describes the resume point and watch-outs cleanly.
No code change.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Capture the in-flight state of the Escalation Mode wedge build so the next
session (or Codex resume) picks up cleanly without re-deriving context:
- CURRENT_TASK now describes the wedge, what's done across the 5 commits on
this branch, what remains (WebSocket push, magic-moment screen, analytics
page, e2e), and the two-metric framing readers MUST internalize before
quoting numbers
- HANDOFF resume point is the WebSocket/SSE push (live-arrival half of the
notification dual-path); includes suggested first slice + watch-outs
(no user_id on ai_session_step, denormalized account_id, peer-escalation
still gated to session owner)
- Both files reference the design doc and the kill-switch criterion
No code change.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- CURRENT_TASK rolls forward — PR #153 closed out, no active task,
with recommended next moves (promote e2e gate to required, pick
from TODO).
- HANDOFF rewritten — new home position is `main`; documents the
e2e job's stub ANTHROPIC_API_KEY convention so future
AI-touching e2e tests know what to expect.
- SESSION_LOG entry extended with the CI env-var diagnosis, the
fix, the merge, and pointers to the natural next pickups.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- CURRENT_TASK.md rolled forward — the CI-recovery task is complete
(PR #150 merged as 87bb20b; backend gate is in required checks).
Active task is now landing PR #153.
- HANDOFF.md rewritten — new resume point is watching CI on the
rebased SHA 1559feb and merging when all three checks are green.
- SESSION_LOG.md gains a 2026-04-26 entry covering the prefill bug
diagnosis, fix, regression test, and the rebase off post-#150 main.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Updates HANDOFF.md, CURRENT_TASK.md, and SESSION_LOG.md to reflect:
- PR #150 now contains the AI-provider test mock + caching + maxfail.
Backend CI should be fully green for the first time in months.
- PR #151 stacked on #150: pytest-xdist with per-worker DBs. Local
verification: 22m 27s → 4m 28s (5× speedup), 1076 passed both runs.
- DoD is now: merge #150, then #151, then add CI / backend
(pull_request) to required status checks on main.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Updates HANDOFF.md, CURRENT_TASK.md, and SESSION_LOG.md so the next
session has accurate resume state. Summary of where things are:
- PR #141 (PSA tickets), PR #147 (FlowPilot Phase 1-9), PR #148 (CI
fixes part 1), PR #149 (CI fixes part 2) all merged to main in this
session.
- Branch protection enabled on main: PR-only, CI / frontend required.
- PR #150 (this branch) is the last CI-config PR — adds
DATABASE_TEST_URL to the workflow and pins upload-artifact to v3.
- Next session: watch #150's CI, merge if green, add CI / backend to
required checks, then start on the 54 real backend test failures.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Codex review of the dual-agent handoff migration flagged factual errors
carried over verbatim from the pre-migration CLAUDE.md. All claims
verified against the live code before correction.
PROJECT_CONTEXT.md — SaaS shape:
- Role hierarchy was `super_admin > team_admin > engineer > viewer`,
but `backend/app/core/permissions.py:4` and
`frontend/src/hooks/usePermissions.ts:4` both define it as
`super_admin > owner > engineer > viewer`. The `team_admin` concept
exists separately as an orthogonal team-scoped gate
(`require_team_admin`, `is_team_admin=True` + valid `team_id`), not
a level in the primary hierarchy.
- Dep list was missing `require_account_owner` and `require_team_admin`,
both present in `backend/app/api/deps.py`.
PROJECT_CONTEXT.md — directory tree:
- `api/endpoints/` comment listed 11 routers; `api/router.py` actually
registers 50+. Replaced with a summary that points at `router.py` as
the source of truth instead of trying to maintain a freezing list.
- `services/psa/` comment omitted `exceptions.py` and `ticket_context.py`,
both present in the directory.
CURRENT_TASK.md + TODO.md:
- Replaced `<!-- EXAMPLE -->` placeholders with clearer empty-state
sentinels so a resume agent sees "no real task yet" at a glance
rather than placeholder acceptance criteria that look unresolved.
SESSION_LOG.md updated with a follow-up bullet documenting this pass.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Split the monolithic CLAUDE.md into a durable handoff system:
- .ai/PROJECT_CONTEXT.md — stable architectural truth (stack, structure,
SaaS shape, ConnectWise, coding standards, frontend patterns, critical
lessons). Ported verbatim from the previous CLAUDE.md.
- .ai/CURRENT_TASK.md — single active task with DoD + out-of-scope.
- .ai/HANDOFF.md — resume point, kept under ~2K tokens.
- .ai/TODO.md — backlog, read only when CURRENT_TASK complete.
- .ai/DECISIONS.md — append-only architectural decision log.
- .ai/SESSION_LOG.md — append-only chronological history.
- .ai/README.md — human-facing explanation of the system.
Root agent files share a byte-identical protocol block (verified via diff):
- CLAUDE.md — primary agent, with GitNexus + gstack tooling and the
Claude Opus 4.7 co-author trailer.
- AGENTS.md — OpenAI Codex resume agent, with grep/rg fallbacks and the
Codex co-author trailer. Steps in when Claude hits session/weekly
limits.
Legacy root-level SESSION-HANDOFF.md deleted — superseded by .ai/HANDOFF.md.
It was a self-describing one-off from the Design System v4 migration and
had no external references.
Supersedes previous CLAUDE.md. Old version recoverable via
`git show pre-ai-handoff:CLAUDE.md` (tag points at commit e110fed).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
