Explicit step completion tracking and unified stage status#102
Merged
nicpottier merged 8 commits intomainfrom Feb 21, 2026
Merged
Explicit step completion tracking and unified stage status#102nicpottier merged 8 commits intomainfrom
nicpottier merged 8 commits intomainfrom
Conversation
Replace brittle inference from node_data existence with an explicit step_completions DB table. The DB is now the single source of truth for stage completion — the frontend SSE handler only tracks running/progress/error state, never "done". - Add step_completions table (schema v7) with backfill migration - Record completions in step-runner on step-complete/step-skip events - Simplify step-status endpoint to read from step_completions - Use invalidateQueries (not removeQueries) to prevent cache flash - Require ALL steps done for stage completion (parallel DAG execution) - Unify StageSidebar and BookView: DB completion overrides SSE state - Make spinning icon a click no-op (stop propagation to parent Link) - Scope page preview hover to thumbnail image only - Update GUIDELINES.md with step completion and cache patterns
Replace dual-source status tracking (local SSE state + server query cache) with a single unified hook. Backend step-status endpoint now merges StageService run state with DB step_completions. SSE connection is always-on and patches TanStack Query cache directly. All stage/settings views now use useBookRun() instead of useStageRun() + useIsStageDone(). Deletes 5 old hook files (~575 lines), net -620 lines.
Remove references to deleted hooks (use-step-run, step-run-invalidation, use-stage-completion). Document always-on SSE, cache-patching approach, and unified step-status endpoint. Add ADR #22 for the single-source stage/step status decision. Also remove unused Volume2 import and add SSE reconnection refetch handler.
The step-status endpoint moved from book routes to stage routes (requires StageService). Update tests to use createStageRoutes with a mock StageService and assert the new response format (stages/steps as string states instead of booleans).
Move gear (settings) and refresh (repackage) icons from the top bar into each stage's sidebar row. Icons clip naturally with overflow-hidden when the rail collapses, and fade in on hover for non-active stages.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replace brittle inference of step completion from data existence with an explicit
step_completionsDB table. The DB is now the authoritative source for stage completion — the frontend SSE handler only tracks running/progress/error state, never "done".Key changes:
step_completionstable with schema v7 migration + backfill for existing booksstep-complete/step-skipeventinvalidateQueries(neverremoveQueries) to prevent completed stages flashing to "unrun" during refetchTest Plan