Polish populated workflow guidance

CHANGELOG.md

@@ -7,6 +7,14 @@
 
 # Changelog
 
+## Sprint 91 populated workflow audit polish (2026-06-21)
+
+- Audited the live populated demo workflow on `http://192.168.10.150:1202` across Overview, Data, Map, QA/QC, AI Labs and Exports.
+- Tightened the Overview workflow guidance complete state so a fully populated flow shows `Ready for handoff` instead of another next-step prompt.
+- Clarified the Map guidance detail by separating rendered layer feature count from AOI context.
+- Added regression coverage for complete-state copy and precise Map guidance copy.
+- No API contracts, migrations, backend behavior, provider fetching or AI model behavior changed.
+
 ## Sprint 90 workflow guidance polish (2026-06-20)
 
 - Added an Overview workflow guidance rail for the V1 path: Project & AOI, Data, Map, QA / AI and Export.

backend/tests/test_sprint90_workflow_guidance.py

@@ -40,3 +40,13 @@ def test_workflow_guidance_has_responsive_contracts() -> None:
     assert ".workflow-guidance-step-active" in css
     assert ".workflow-step-status" in css
     assert "grid-template-columns: repeat(auto-fit, minmax(8rem, 1fr));" in css
+
+
+def test_workflow_guidance_complete_state_and_map_copy_are_precise() -> None:
+    app = (ROOT / "frontend" / "src" / "App.tsx").read_text(encoding="utf-8")
+
+    assert "workflowGuidanceComplete" in app
+    assert "Ready for handoff" in app
+    assert "layer feature" in app
+    assert "+ AOI" in app
+    assert "AOI loaded" in app

docs/CODEX_EXECUTION_LOG.md

@@ -3276,3 +3276,31 @@ Limitations:
 
 Next recommended pass:
 - After deploy and visual validation, continue with any remaining end-to-end workflow handoff polish surfaced by the live audit.
+
+## Sprint 91 populated workflow audit polish (2026-06-21)
+
+Changed:
+- Audited the live populated demo state on `http://192.168.10.150:1202` across Overview, Data, Map, QA/QC, AI Labs and Exports.
+- Changed the Overview workflow guidance badge to show `Ready for handoff` when project, dataset, map, QA/AI and export state are all present.
+- Clarified the Map workflow step so it reports layer feature count separately from AOI context and shows `AOI loaded` for AOI-only map context.
+- Extended `backend/tests/test_sprint90_workflow_guidance.py` with complete-state and Map-copy regression coverage.
+- Updated `frontend/README.md`, `docs/TODO.md` and `CHANGELOG.md`.
+
+Tested:
+- Live pre-change browser audit passed for the populated demo workflow: Data had 2 ready datasets, Map rendered `demo_predicted_buildings.geojson` with 2 layer features, QA/QC showed 2 checks, AI Labs showed model/result/QA surfaces, Exports showed 50 artifacts, and no checked workspace had console warnings/errors or horizontal overflow.
+- Red step: `python -m pytest backend/tests/test_sprint90_workflow_guidance.py -q` failed on missing `workflowGuidanceComplete` / `Ready for handoff` / precise Map copy contracts.
+- Post-deploy live check found the AOI-only reload state rendered `0 layer features + AOI`; a second red step failed on missing `AOI loaded` copy before the fix.
+- `python -m pytest backend/tests/test_sprint90_workflow_guidance.py -q` (`4 passed`)
+- `python -m pytest backend/tests/test_sprint90_workflow_guidance.py backend/tests/test_sprint83_workspace_panel_hierarchy.py backend/tests/test_sprint82_shell_density_polish.py -q` (`10 passed`)
+- `cd frontend && npm run typecheck`
+- `cd frontend && npm run build`
+- Local browser UI check against `http://127.0.0.1:5174` passed for the Overview guidance panel with no horizontal overflow. Local console showed expected Vite proxy 500s because only the frontend server was running.
+
+Open:
+- Full readiness, Tower deploy and live post-change browser validation still pending for this pass.
+
+Limitations:
+- Frontend Overview copy/state polish only; no API contract, persistence, migration, provider fetching or AI/model behavior changes.
+
+Next recommended pass:
+- After deploy and live validation, continue with any remaining populated-state visual issues found in the next audit.

docs/TODO.md

@@ -362,3 +362,4 @@ This file now starts with the current implementation status. Older preparation/b
 - [x] Add mobile overflow hardening for workbench navigation, inspector and long QA identifiers.
 - [x] Add QA/QC result filtering and density controls for long-running demo projects.
 - [x] Add Overview workflow guidance for the V1 project -> data -> map -> QA/AI -> export path.
+- [x] Audit populated demo workflow and tighten complete-state Overview guidance copy.

frontend/README.md

@@ -249,6 +249,7 @@ Detection Lab and Segmentation Lab now share the same AI workspace hierarchy: mo
 - The shell includes a keyboard skip link, an explicit primary workspace navigation label and compact horizontal context/navigation rails on narrow screens so active workspace content is reachable without a tall preamble.
 - The Overview workspace separates readiness, status tiles and recommended next actions into distinct visual hierarchy regions, keeping the first screen scannable without changing workflow behavior.
 - The Overview workspace now also shows a compact workflow guidance rail for the V1 path from project and AOI setup through data, map review, QA/AI validation and export handoff.
+- When the V1 workflow is populated end to end, the Overview rail switches to a `Ready for handoff` state and keeps map guidance explicit about layer features versus AOI context.
 - The Data workspace surfaces selected project, AOI and dataset context before creation/upload forms, then separates form and catalog/list regions for faster scanning.
 - The Export Center includes a handoff readiness summary, grouped artifact actions and provenance-rich export cards so report/GeoJSON handoff stays understandable in long-running demo projects.
 

frontend/src/App.tsx

@@ -450,11 +450,13 @@ function App(): JSX.Element {
     setActiveWorkspace('exports')
   }
   const hasAnalysisOutput = qualityChecks.length > 0 || Boolean(changeDetectionResult) || detectionItems.length > 0 || segmentationItems.length > 0
+  const hasMapContext = mapFeatureCount > 0 || areaFeatureCount > 0
+  const workflowGuidanceComplete = Boolean(selectedProjectId) && datasets.length > 0 && hasMapContext && hasAnalysisOutput && exports.length > 0
   const recommendedWorkflowTarget: WorkspaceKey = !selectedProjectId
     ? 'data'
     : datasets.length === 0
       ? 'data'
-      : mapFeatureCount === 0 && areaFeatureCount === 0
+      : !hasMapContext
         ? 'map'
         : !hasAnalysisOutput
           ? 'analysis'
@@ -488,9 +490,13 @@ function App(): JSX.Element {
     {
       step: '3',
       title: 'Map',
-      detail: mapFeatureCount > 0 || areaFeatureCount > 0 ? `${mapFeatureCount + areaFeatureCount} active map feature${mapFeatureCount + areaFeatureCount === 1 ? '' : 's'}` : 'Inspect AOI and selected layer',
-      status: mapFeatureCount > 0 || areaFeatureCount > 0 ? 'ready' : 'waiting',
-      ready: mapFeatureCount > 0 || areaFeatureCount > 0,
+      detail: hasMapContext
+        ? mapFeatureCount > 0
+          ? `${mapFeatureCount} layer feature${mapFeatureCount === 1 ? '' : 's'}${areaFeatureCount > 0 ? ' + AOI' : ''}`
+          : 'AOI loaded'
+        : 'Inspect AOI and selected layer',
+      status: hasMapContext ? 'ready' : 'waiting',
+      ready: hasMapContext,
       target: 'map',
     },
     {
@@ -607,7 +613,9 @@ function App(): JSX.Element {
                     <h2>Project to export path</h2>
                   </div>
                   <span className="status-badge">
-                    Next: {workspaceNavItems.find((item) => item.key === recommendedWorkflowTarget)?.label ?? 'Overview'}
+                    {workflowGuidanceComplete
+                      ? 'Ready for handoff'
+                      : `Next: ${workspaceNavItems.find((item) => item.key === recommendedWorkflowTarget)?.label ?? 'Overview'}`}
                   </span>
                 </div>
                 <div className="workflow-guidance-steps">