UI Interview: Quick-Scan Overview

Review-state alignment page for the assembled chunked UI interview packet. This page renders the complete proposed UI branch packet before canonical writes.

Skill: ui-interview Status: review Date: 2026-07-02 Product path: research/afps-tracker Visual tier: prototype Interview provenance: live-ui-interview

Interview Stage
Rendered Working Packet
Visual Mockup Reference
Review Gates
Compile Responses
Supplemental Source View

Interview Stage

Invocation: $ui-interview quick-scan-overview. Mode: full UI branch-review, chunked assemble-and-approve session.

The required UI assumptions and open decisions were confirmed in the prior interrogation sidecar, and all five page intermediates are present. Review this page, answer the gates, then use the bottom Compile Responses button. Canonical design files and flow-tree updates are blocked until final compiled YAML returns with approval.

Rendered Working Packet

Preliminary UI Interview Research: Quick-Scan Overview

Interview provenance: live-ui-interview

Invocation: $ui-interview quick-scan-overview

Product path: research/afps-tracker

Topic: quick-scan-overview

Status: pre-approval review packet

Alignment page: alignment/ui-interview-quick-scan-overview.html

Interview Stage

This is the chunked-mode assemble-and-approve session for $ui-interview quick-scan-overview in full UI branch-review mode. The UI Assumptions Manifest and open decisions were confirmed in research/afps-tracker/_working/interrogation-ui-interview-r1.yaml, the shared context brief was written at design/afps-tracker/_working/ui-interview-quick-scan-overview-brief.md, and the five page-specific intermediates under design/afps-tracker/ui-interview-quick-scan-overview/ now exist. This packet is not a canonical UI branch packet yet; it is the complete proposed review content for the single binding alignment gate.

Proposed Canonical Destinations

UI branch packet: design/afps-tracker/ui-quick-scan-overview.md
UI interview log: design/afps-tracker/ui-quick-scan-overview-interview.md
Flow-tree manifest update after approval: design/afps-tracker/flow-tree-afps-tracker.yaml
Working packet archive after approval: docs/history/archive/YYYY-MM-DD/HHMMSS/research/afps-tracker/_working/preliminary-ui-interview-research.md

Source Evidence

Shared context brief: design/afps-tracker/_working/ui-interview-quick-scan-overview-brief.md
Whole-branch visual mockup: design/afps-tracker/_working/ui-mockup-quick-scan-overview.html
Interrogation sidecar: research/afps-tracker/_working/interrogation-ui-interview-r1.yaml
Parent flow: design/afps-tracker/user-flow-afps-tracker.md
Parent UX variation: design/afps-tracker/ux-variations-uf-orient-portfolio.md
Flow-tree manifest: design/afps-tracker/flow-tree-afps-tracker.yaml
Page intermediates:
Loading / Scan Page Spec: design/afps-tracker/ui-interview-quick-scan-overview/loading-scan.md
Portfolio Overview Page Spec: design/afps-tracker/ui-interview-quick-scan-overview/portfolio-overview.md
Selected Row Preview Page Spec: design/afps-tracker/ui-interview-quick-scan-overview/selected-row-preview.md
Empty / No-AFPS State Page Spec: design/afps-tracker/ui-interview-quick-scan-overview/empty-no-afps-state.md
Blocking Diagnostic Summary Page Spec: design/afps-tracker/ui-interview-quick-scan-overview/blocking-diagnostic-summary.md

Branch Investigation And Decision Record

Parent user-flow branch: uf-orient-portfolio

Selected UX variation branch: quick-scan-overview

Touched sibling flows: selected-path verification, evidence/provenance inspection, diagnostics recovery, inactive/promoted boundary explanation, handoff/export. These remain outside the Quick-Scan Overview branch except as secondary links or carried context.

Competing or coordinating sibling UX variations: trust-first source health, diagnostics-first recovery, portfolio-map grouping, and command/resume-first orientation from the approved ux-variations packet.

Proposed branch decision: approve this UI experiment as the first Quick-Scan Overview UI branch after review, provided the alignment page receives final compiled YAML approval. Until approval, this remains a review-state packet and must not write canonical UI specs or flow-tree decisions.

Prototype-First Boundary

First clickable journey: scan repo-local AFPS artifacts, show a quick portfolio overview, select a route-safe active or warning-level path, and hand off to selected-path verification with trust and warning context preserved.

Experiment route map: Loading / Scan -> Portfolio Overview -> Selected Row Preview, with alternate outcomes to Empty / No-AFPS State and Blocking Diagnostic Summary.

Fixture or fake data: allowed for scan status, path counts, grouped rows, source-health states, warning counts, diagnostic refs, and selected path facts.

Visually mocked infrastructure only: repo-local scanning, source parsers, diagnostics source refs, trust/confidence derivation, and downstream sibling-flow routes.

Deferred production infrastructure: file watcher, persistent storage, source mutation/write-back, auth, accounts, collaboration, deployment, analytics, command execution, copy-next-command, final handoff/export.

Evidence required before implementation planning promotes deferred infrastructure: prototype evaluation showing operators can orient quickly without losing source-trust visibility, and UAT evidence that warning/blocked/suppressed states are understood before continuation.

Coverage Checkpoint

Pages covered: Loading / Scan, Portfolio Overview, Selected Row Preview, Empty / No-AFPS State, Blocking Diagnostic Summary.
Components covered: header shell, source-health strip, count summary, grouped path rows, selected preview, empty result panel, diagnostic banner/panel, affected-source list, disabled primary route block, secondary source/diagnostic/boundary links.
Controls covered: row select, explain, review, group collapse, source-health link, warnings link, primary Continue to verify path, inspect source, review diagnostics, scan again, collapse preview.
States covered: loading, slow loading, prior-state retained, early warning, early blocking, clean portfolio, warning-level portfolio, partial source, multiple active paths, promoted/inactive context, unresolved active refs, clean empty, missing source, unreadable/malformed source, unsupported/out-of-scope, blocking with readable rows, blocking with no trustworthy rows, error, offline.
Responsive coverage: desktop/wide desktop, tablet under about 1040px, mobile under about 700px, no horizontal table requirement for first value.
Accessibility coverage: labelled regions, keyboard order, disabled reasons, warning severity announcements, touch targets, reduced motion, color-blind safe state treatment, screen reader names.
Unresolved risks: warning prominence could be too subtle; context groups could distract from active selection; selected preview could absorb verification if over-detailed; disabled/suppressed reasons must be explicit enough to preserve trust.

---

UI Interview Brief: Quick-Scan Overview

Invocation: $ui-interview quick-scan-overview

Product path: research/afps-tracker

Parent user-flow branch: uf-orient-portfolio

Selected UX variation branch: quick-scan-overview

Visual mockup: design/afps-tracker/_working/ui-mockup-quick-scan-overview.html

Interrogation sidecar: research/afps-tracker/_working/interrogation-ui-interview-r1.yaml

Confirmed UI Assumptions Manifest

ID	Source	Decision	Resolved meaning
product-user	[from spec]	Confirmed	Primary user is an AFPS power user / AI workflow operator returning to repo-local AFPS state after context loss, session restart, compaction, handoff, or branch-state review.
branch-boundary	[from artifact]	Confirmed	This UI branch covers only orientation to the product portfolio: open tracker, scan active and parallel paths, and select one path for deeper verification.
coordination	[from artifact]	Confirmed	Selected-path verification, evidence/provenance inspection, diagnostics recovery, handoff/export, and inactive/promoted boundary explanation stay sibling flows.
pages-routes	[from artifact]	Confirmed	The branch has five screen/state surfaces: Loading / Scan, Portfolio Overview, Selected Row Preview, Empty / No-AFPS State, and Blocking Diagnostic Summary.
hierarchy	[from research]	Confirmed	First-screen hierarchy is source-health strip, count summary, grouped path list, row-level warnings, then selected preview.
controls-states	[from codebase]	Confirmed	Controls and states preserve source-native trust envelopes, warning visibility, disabled reasons, and normal-route suppression rules from the approved model.
visual-stack	[inferred]	Confirmed	Use a restrained, utilitarian web UI mockup with static/local data and no production storage, auth, networking, or write-back implementation.

Confirmed Open Decisions

Warnings in the first screen: use a persistent source-health strip plus row-level warning badges. Blocking issues interrupt the quick path with a banner. Non-blocking warnings stay visible without taking over row scanning.

Selected-path preview depth: show label, status, stage, trust level, warning count, and the enabled or disabled reason for Continue to verify path. Exclude copy-next-command and full evidence/provenance detail from the orientation screen.

Default layout: desktop uses a top source-health strip, count summary, grouped path list, and right-side selected preview. Tablet and mobile move the selected preview into an inline expansion below the selected row.

Scope Boundaries

The branch may show portfolio-level source health, path counts, grouped rows, row-level warning badges, selected row highlight, a compact selected-row preview, suppressed-route reasons, and secondary links into sibling flows.

The branch must not expose primary copy-next-command behavior, full evidence/provenance detail, write-back controls, command execution, account/collaboration controls, storage architecture, file watcher behavior, or implementation sequencing.

Page Inventory

Loading / Scan

Purpose: communicate that AFPS Tracker is reading repo-local source files. It shows the repository label, scan status, source-health/count skeletons, grouped-row skeletons, and any early source-access diagnostic placeholder. Loading must not imply network activity. Prior state, if retained later, must be labelled as prior until the current scan completes.

Portfolio Overview

Purpose: let the operator orient and select. It shows the header, source-health strip, portfolio count summary, grouped active/parallel/context rows, row select affordances, warning badges, trust badges, suppressed-route reasons, and secondary source-health links.

Selected Row Preview

Purpose: confirm selection without turning orientation into selected-path verification. On desktop it appears as a right-side preview. On tablet and mobile it becomes an inline expansion below the selected row. It shows only compact selection facts and the enabled/disabled reason for Continue to verify path.

Empty / No-AFPS State

Purpose: avoid fabricated guidance. It names the source checked, explains that no AFPS product paths were found, exposes relevant diagnostics, and avoids active-route guidance when source artifacts do not support it.

Blocking Diagnostic Summary

Purpose: preserve orientation while preventing false confidence. It interrupts the quick path with a banner, names affected source files/path refs, keeps readable rows visible, and disables or suppresses unsafe actions with explicit reasons.

The first UI proposal uses a shallow shell: repository title, source scan freshness, source-health strip, count summary, grouped path list, and selected preview. No global sidebar is required for this branch. Secondary navigation is limited to source health, row diagnostics, boundary explanation, evidence inspection, and provenance inspection as links into sibling flows.

The primary action is Continue to verify path. It is enabled only when a selected path is active or warning-level and not blocked by contradiction, unreadable required source, promoted boundary, out-of-scope boundary, unresolved ref, or malformed source. The action carries selected path ID, trust level, parser confidence, source confidence, warnings, and diagnostic refs forward.

Evaluation Criteria

First-value clarity: the operator can identify active and parallel paths within a few seconds.

Source-trust visibility: warning, partial, blocked, unresolved, inactive, and promoted states are visible before selection.

Branch-selection speed: the user can select a path without opening diagnostics first when source state is clean or warning-level.

Boundary safety: inactive, promoted, archived, deferred, revisit-candidate, unresolved, contradicted, unsupported, and out-of-scope paths do not appear as normal active routes.

Preview discipline: selected preview remains compact and does not absorb selected-path verification, evidence/provenance inspection, or handoff/export behavior.

Responsive viability: desktop side preview becomes an inline expansion on tablet/mobile without requiring a horizontal table for first value.

Carried Branch Decision Context

The approved UX variation set recommends quick-scan-overview as the first UI branch under uf-orient-portfolio. This brief does not approve the UI experiment. It only carries confirmed assumptions and the whole-branch mockup into chunked page-specific specification sessions.

---

Page Intermediate: Loading / Scan Page Spec

Source file: design/afps-tracker/ui-interview-quick-scan-overview/loading-scan.md

Loading / Scan Page Spec

Scope

The Loading / Scan page is the first transient surface in the Quick-Scan Overview branch. It communicates that AFPS Tracker is reading repo-local AFPS source artifacts, preserves trust boundaries while the current scan is unresolved, and prepares the operator for the Portfolio Overview, Empty / No-AFPS State, or Blocking Diagnostic Summary.

This page must not imply network activity, background account sync, production storage, file watcher behavior, command execution, write-back, or final handoff readiness. It may show retained prior scan information only when every retained value is labelled as prior state until the current scan completes.

Source Evidence

Confirmed brief: design/afps-tracker/_working/ui-interview-quick-scan-overview-brief.md
Whole-branch mockup reference: design/afps-tracker/_working/ui-mockup-quick-scan-overview.html
Parent UX variation: design/afps-tracker/ux-variations-uf-orient-portfolio.md
Parent flow branch: uf-orient-portfolio

User Goal And Success Condition

The operator should understand, within a second or two, that AFPS Tracker is scanning local repository artifacts and has not yet produced current portfolio guidance.

Success conditions:

Repository identity is visible.
Scan status is explicit and local-source framed.
Placeholder structure previews the same information architecture as the resolved overview.
Early source-access problems can appear without fabricating portfolio results.
Prior retained data, if shown, cannot be confused for the current scan result.

Layout Anatomy

Desktop And Wide Desktop

Use the same shallow shell as the resolved overview so the page does not reflow dramatically after scan completion:

Header strip at the top, full width, 64-76px tall.
Main content constrained to the same max width as the overview, approximately 1360px.
Source-health placeholder strip directly below the header.
Count-summary skeleton row below the source strip.
Main workspace grid with grouped-row skeletons on the left and a scan-status / prior-state panel on the right.
Optional early diagnostic banner above the source-health placeholder when source access fails before path parsing begins.

Desktop grid:

Main content horizontal padding: 40px on wide desktop, 24px on standard desktop.
Vertical gap between major regions: 16-22px.
Workspace grid: minmax(0, 1fr) 360px, matching the overview preview width.
Right panel remains sticky only after enough vertical content exists; during short loading states it can stay static to avoid awkward scroll behavior.

Tablet

At widths below approximately 1040px:

Collapse workspace to one column.
Keep the source-health placeholder before the count placeholders.
Move the scan-status / prior-state panel below the grouped-row skeletons.
Avoid horizontal scrolling for row skeletons.

Mobile

At widths below approximately 700px:

Header stacks repository label and scan state.
Source-health placeholder becomes a vertical list.
Count placeholders stack one per row.
Grouped-row skeletons use card-like vertical anatomy, not table columns.
Right-side scan-status panel becomes an inline section after the first grouped skeleton block.

Component Inventory

Content:

Product title: AFPS Tracker
Repository label: Repository: {repo_path_or_label}
Scan state indicator: animated or static status dot plus text.

Default scan text:

Scanning repo-local AFPS artifacts...

If a scan is taking longer than expected:

Still scanning repo-local AFPS artifacts...

The header must not say syncing, uploading, connecting, or any phrase that implies a remote service.

Source-Health Skeleton Strip

Purpose: reserve the resolved source-health position while avoiding claims before scan completion.

Cells:

Source health
Parser confidence
Source confidence
Unresolved refs
Blocking issues

Each cell uses:

A small uppercase label.
A skeleton value bar or Checking... text.
No clean/warning/blocked color until the scan knows the value.

If an early source-access diagnostic exists, this strip may show a warning or blocked state only for the affected source-access fact, with unresolved fields still shown as checking.

Count Summary Skeletons

Purpose: reserve portfolio count positions.

Cards:

Active paths
Parallel context
Inactive/context paths
Promoted boundary

Each card shows a skeleton number block and label. Do not show zero counts while the scan is incomplete unless the scan has definitively reached the no-AFPS state.

Grouped Row Skeletons

Purpose: preview the row-scanning structure used by the Portfolio Overview.

Groups:

Active Paths
Parallel / Context Paths
Inactive And Boundary Context, only if prior state or scan metadata justifies showing the group placeholder.

Each group contains 2-3 row skeletons with stable column positions:

Path title / path ID block
Status badge placeholder
Stage placeholder
Next safe branch placeholder
Warning badge placeholder
Select action placeholder

The Select placeholder must be visibly disabled and must not be clickable while the current scan is unresolved.

Scan-Status / Prior-State Panel

Desktop location: right column.

Tablet/mobile location: inline below the grouped skeletons.

Content:

Heading: Reading local sources
Current source list, if available:
research/.progress.yaml
Product-path scoped research/design artifacts when known
Alignment or design-tree manifest refs when known
Current scan phase:
Locating product paths
Reading path status
Checking warnings
Preparing overview
Prior-state notice when retained values are displayed.

Prior-state notice copy:

Prior scan data may be shown for orientation only. Current actions stay disabled until this scan completes.

Show this only when the scan has already detected a source-access issue before portfolio rows are trustworthy.

Warning copy:

Some source files are still being checked. The overview will keep actions disabled until source trust is known.

Blocking copy:

AFPS Tracker cannot finish the local scan yet. Review the source issue before using portfolio guidance.

The banner links only to a diagnostics sibling flow placeholder when such a route exists in the prototype. It must not expose repair commands on this page.

Control Inventory

Disabled Row Select Placeholders

Label:

Select

State:

Disabled while loading.

Disabled reason:

Selection is unavailable until the current source scan completes.

Screen reader name:

Select path unavailable until scan completes

Secondary Link: Source Health

Label:

Source health

Behavior:

If the prototype includes the sibling source-health route, this navigates to source/provenance or diagnostic inspection.
During loading, it may be visible but disabled until diagnostic refs exist.

Disabled reason:

Source health details are not available until source refs are known.

Secondary Link: Diagnostics

Label:

Diagnostics

Behavior:

Enabled only when an early warning or blocked source-access issue exists.
Routes to the diagnostics recovery sibling flow, carrying diagnostic refs.

Disabled reason:

No diagnostic refs are available yet.

Primary Action Placeholder

The page may reserve space for Continue to verify path, but the action must be disabled or hidden while loading.

Disabled reason:

Choose a path after the scan completes.

Do not show copy-next-command, export, handoff, write-back, or command execution controls.

Copy Requirements

Use concise, source-native language:

Heading: Scanning portfolio
Helper: Reading repo-local AFPS artifacts before showing active paths.
Locality note: No network activity is required for this scan.
Prior-state label: Prior scan
Current-state label: Current scan
Completion transition text, if needed: Scan complete. Preparing overview...

Avoid:

Tutorial copy.
Marketing language.
System architecture promises.
Phrases that imply cloud sync, background automation, or mutation of source files.

Interaction States

Default Loading

Header scan dot uses subtle motion or a static pulsing treatment.
Source-health strip, count cards, and rows show skeletons.
Select and continue actions are disabled.
No warning or clean state is implied before known.

Slow Loading

Trigger when scan exceeds the prototype's chosen loading threshold.

Replace default helper with Still scanning repo-local AFPS artifacts...
Keep skeleton layout stable.
Show source list or current phase if available.
Do not create a retry action unless the underlying prototype actually supports retry.

Prior State Retained

Prior values can appear muted below skeletons or inside the right panel.
Every retained value must be labelled Prior scan.
Any action derived from prior state remains disabled.
Current scan skeletons remain visually primary.

Early Warning

Show non-blocking banner.
Keep scan progress visible.
Diagnostics link may become enabled when diagnostic refs exist.
Row placeholders remain disabled.

Early Blocking Issue

Show blocking banner above the source-health strip.
Keep any readable source facts visible.
Suppress or disable path-selection and continue actions with explicit reasons.
Route next resolved surface to Blocking Diagnostic Summary instead of Portfolio Overview when the scan cannot produce trustworthy path rows.

Empty Completion Transition

When the scan completes and no AFPS paths exist:

Do not briefly show zero counts on this page as if it were the overview.
Transition directly to Empty / No-AFPS State.
If an intermediate text is needed, use No AFPS product paths found in checked sources.

Error

For unrecoverable UI-level rendering errors, show a compact error region within the shell:

The scan result could not be displayed.
Include a diagnostics link only if diagnostic refs exist.
Do not invent source facts.

Offline

Offline status should not block a local scan unless the app shell itself requires unavailable assets. If shown, label it separately:

Network is offline. Local repository scan can continue.

Visual And Spatial Rules

Keep cards and panels at 8px radius or less.
Use restrained neutral surfaces with clear warning and blocked accents only when those states are known.
Skeleton blocks should be low-contrast and distinct from actual values.
Loading motion must be subtle, not central to the page.
The source-health placeholder must remain first in the content hierarchy.
Count cards should maintain fixed minimum heights so the completion transition does not jump.
Row skeletons should match resolved row height closely, approximately 68-76px on desktop.
Mobile row skeletons may expand vertically but should keep consistent spacing.

Accessibility Requirements

Main loading region uses aria-busy="true" while scan is unresolved.
Scan status text is exposed through a polite live region.
Blocking diagnostic banner uses assertive announcement only when it appears after initial render.
Skeleton-only content must have accessible labels; do not rely on visual shimmer.
Disabled controls must include programmatic disabled state and visible disabled reasons.
Keyboard order:

Header repository context
Source-health / diagnostic banner
Count summary placeholders
Grouped skeleton sections
Scan-status / prior-state panel
Enabled diagnostics/source links, if any

Touch targets for any enabled link or button must be at least 44px high.
Respect reduced motion by disabling shimmer/pulse animation and using static skeletons.
Color cannot be the only warning indicator; include text labels such as Warning and Blocked when those states are known.

Data Requirements

Fields this page may consume:

Repository label or path.
Scan status: pending, scanning, slow, warning, blocked, complete.
Current scan phase.
Source file labels being checked.
Optional prior scan timestamp and prior summary values.
Early diagnostic refs, severity, affected source, and summary.

Fields this page must not require:

Full evidence/provenance detail.
Copyable next command.
Handoff/export metadata.
Auth/account data.
Remote sync state.
Production persistence status.

Transition Rules

On successful scan with one or more paths: transition to Portfolio Overview.
On successful scan with no AFPS paths: transition to Empty / No-AFPS State.
On blocking source issue: transition to Blocking Diagnostic Summary or keep the banner visible until the user follows diagnostics.
On warning-level issue: continue to Portfolio Overview with warning counts and row-level warning badges preserved.
If exactly one safe active path is known after completion, the next page may preselect it, but this loading page must not preselect during scan.

Downstream Handoff Constraints

The Loading / Scan page passes only scan status, source-health summary, diagnostic refs, and prior-state labels forward. It does not pass selected path context because selection cannot happen here.

The later screen builder should treat this as one flow-step batch that establishes the shell and loading placeholders before resolved overview content is layered on top.

Open Risks

If prior scan values are too visually prominent, users may mistake stale data for current guidance.
If loading lasts long enough to need retry, the retry behavior must be model-backed before a button appears.
If early diagnostics are available, the page must show enough issue context to preserve trust without absorbing the full diagnostics recovery flow.

---

Page Intermediate: Portfolio Overview Page Spec

Source file: design/afps-tracker/ui-interview-quick-scan-overview/portfolio-overview.md

Portfolio Overview Page Spec

Scope

The Portfolio Overview page is the primary first-value surface for the Quick-Scan Overview branch. It appears after the repo-local scan has produced a trustworthy enough portfolio snapshot and lets an AFPS operator orient to active, parallel, inactive/context, promoted, unresolved, and warning-level paths without reading raw source files.

This page may show portfolio-level source health, path counts, grouped rows, row warnings, trust badges, suppressed-route reasons, selected-row highlight, and compact links into sibling flows. It must not absorb selected-path verification, evidence/provenance inspection, diagnostics recovery, handoff/export, copy-next-command behavior, write-back controls, account/collaboration features, production storage, or command execution.

Source Evidence

Confirmed brief: design/afps-tracker/_working/ui-interview-quick-scan-overview-brief.md
Whole-branch mockup reference: design/afps-tracker/_working/ui-mockup-quick-scan-overview.html
Parent UX variation: design/afps-tracker/ux-variations-uf-orient-portfolio.md
Parent flow branch: uf-orient-portfolio
Existing intermediate style reference: design/afps-tracker/ui-interview-quick-scan-overview/loading-scan.md

User Goal And Success Condition

The operator should identify active and parallel product paths, understand source trust and warnings, and select one path for deeper verification within a few seconds.

Success conditions:

Repository identity and scan freshness are visible.
Source health appears before path selection.
Active paths appear first and are scannable without expanding every row.
Warning, partial, blocked, unresolved, inactive, promoted, archived, deferred, revisit-candidate, unsupported, and out-of-scope states are visible before action.
Selectable active or warning-level rows can be chosen without forcing diagnostic triage first.
Unsafe rows show explicit suppressed-route reasons instead of normal active continuation.
The page can pass a selected active/warning path into selected-path verification with trust, parser confidence, source confidence, warnings, and diagnostic refs preserved.

Layout Anatomy

Desktop And Wide Desktop

Use a shallow, operational dashboard layout with the source-trust envelope above the path list:

Header strip at the top, full width, 64-76px tall.
Main content constrained to approximately 1360px, centered on very wide screens.
Source-health strip directly below the header.
Portfolio count summary below source health.
Workspace grid with grouped path rows on the left and selected preview on the right.
Optional warning or blocking banner above grouped rows when portfolio-level issues affect route safety.

Desktop spacing:

Main content horizontal padding: 40px on wide desktop, 24px on standard desktop.
Major vertical gaps: 16-22px.
Workspace grid: minmax(0, 1fr) 360px.
Left column minimum usable width: 680px.
Right preview width: 340-380px.
Row height: approximately 72-88px for dense desktop rows.
Group gap: 16px.

The selected preview may be sticky below the header once content scrolls, but it must not cover source-health or warning banners. If the viewport is too short, keep the panel static and let the page scroll normally.

Tablet

At widths below approximately 1040px:

Collapse the workspace to one column.
Keep source-health and counts above rows.
Replace the right-side preview with an inline selected-row expansion beneath the selected row.
Keep row columns for label/status/stage/warnings/select, while moving secondary metadata into a second line.
Avoid horizontal scrolling.

Mobile

At widths below approximately 700px:

Header stacks product title, repository label, and scan freshness.
Source-health strip becomes stacked status blocks.
Count summary becomes a two-column grid or single-column stack on narrow phones.
Grouped rows become compact list items with visible badges and a 44px minimum select affordance.
Selected preview appears immediately below the selected row.
Group metadata and secondary links collapse into concise text rows.
No horizontal table is required for first value.

Component Inventory

Content:

Product title: AFPS Tracker
Repository label: Repository: {repo_path_or_label}
Scan freshness: Scan complete {relative_time} or Local scan complete
Optional source timestamp when known.

The header must frame the page as repo-local orientation. Avoid sync, upload, connected, or other remote-service language.

Source-Health Strip

Purpose: make source trust visible before any row is selected.

Cells:

Source health: clean, warning, partial, blocked.
Parser confidence: high, medium, low, unknown.
Source confidence: source-backed, inferred, partial, missing, contradicted.
Active refs: count and unresolved count.
Blocking issues: count and warning count.

Each cell contains:

A concise label.
A value.
Optional source file or diagnostic ref summary when needed.

State rules:

Clean state may use a restrained positive accent but still shows source labels.
Warning state uses text plus color, not color alone.
Blocked state becomes visually prominent and must be paired with disabled/suppressed route reasons in rows.
Partial state must not read as clean; use Partial source or Warning-level source.

Portfolio Count Summary

Cards:

Active paths
Parallel context
Inactive/context paths
Promoted boundary

Optional cards when source evidence supports them:

Unresolved refs
Blocked routes
Out-of-scope

Each card shows a number, label, and short state hint when useful. Counts must be source-derived; do not show fabricated zeroes for categories the source did not evaluate.

Grouped Path List

Default group order:

Active Paths
Parallel And Boundary Context
Inactive / Deferred / Archived Context, only when present and useful
Unresolved Or Blocked Refs, either as its own group or visibly inside the affected group

Group header content:

Group title.
One-line group meta, such as Selectable rows preserve warning context into verification.
Optional group-level warning count.
Optional collapse toggle only for non-primary context groups.

Active Paths should be open by default. Context groups may be open by default when they contain warnings, promoted boundaries, unresolved refs, or suppressed-route facts that matter to the first-value read.

Product-Path Row

Canonical row content:

Path label.
Path ID.
Scope path.
Status or boundary badge.
Pipeline stage.
Next safe branch, next skill, or suppression reason.
Last touched, when available.
Trust level.
Warning or diagnostic count.
Select, explain, review, or disabled action.

Variations:

Clean active row: selectable, trust badge reads clean/source-backed.
Warning active row: selectable only if no blocking diagnostic affects selected-path verification; warning count remains visible.
Parallel/context row: can be selectable for explanation or preview, but normal active continuation is suppressed unless model marks it active/warning-level.
Promoted or inactive row: action is Explain, not Continue.
Unresolved row: action is Review or disabled; normal active route blocked.
Contradicted, malformed, unreadable, unsupported, out-of-scope, or blocked row: disabled/suppressed with visible reason.

Rows must not hide warnings behind hover-only controls. The row should remain understandable with no pointer hover.

Warning And Diagnostic Badges

Badge labels:

Clean
{n} warnings
Blocked
Unresolved
Partial source
Promoted
Inactive
Archived
Deferred
Out of scope

Badges use color, label text, and icon or shape variation where available. Warning and blocked badges must expose accessible names with severity and count.

Selected Preview Region

On desktop, the selected preview lives in the right column. On tablet and mobile, it belongs to the Selected Row Preview page/state as an inline expansion under the selected row.

Portfolio Overview owns the placement and row-selection trigger, but the detailed selected preview content is specified in selected-row-preview.md. The overview must reserve enough space and selected context for that page/state without expanding into full verification.

Control Inventory

Row Select Button

Labels:

Select
Selected

Behavior:

Selects an active or warning-level path for compact preview.
Updates selected-row highlight.
Enables Continue to verify path only when selected path is route-safe.
Preserves selected path ID, trust level, parser confidence, source confidence, warning IDs, and diagnostic refs.

Disabled reason examples:

Selection is unavailable because this path is unresolved.
Selection is unavailable because required source support is unreadable.
Selection is unavailable because this path is promoted and normal active routing is suppressed.

Screen reader names:

Select {path_label} path
{path_label} path selected
Select unavailable for {path_label}: {disabled_reason}

Explain Button

Label:

Explain

Behavior:

Routes inactive, promoted, archived, deferred, revisit-candidate, unsupported, or out-of-scope rows to the boundary explanation sibling flow.
Carries path ID, boundary kind, source refs, trust level, warnings, and suppression reason.

This control must not look like normal active continuation.

Review Button

Label:

Review

Behavior:

Routes unresolved, malformed, contradicted, unreadable, or blocked refs to diagnostics recovery or source-health inspection.
Carries diagnostic refs and affected source paths.

Group Collapse Toggle

Use only for secondary context groups when the list becomes long.

Labels:

Show {group_name}
Hide {group_name}

Rules:

Active Paths should not be collapsed by default.
Groups containing blocking issues, unresolved active refs, or promoted boundary warnings should remain open or show a prominent count when collapsed.
Toggle state must be keyboard accessible and announced with expanded/collapsed state.

Secondary Link: Inspect Source Health

Label:

Inspect source health

Behavior:

Opens portfolio-level source/provenance or diagnostics sibling flow.
Carries source-health summary, parser confidence, source confidence, unresolved refs, and diagnostic refs.

Disabled or hidden only when no source refs exist. If disabled, show: Source health details are unavailable because source refs were not produced.

Secondary Link: Review Warnings

Label:

Review warnings

Behavior:

Opens warnings or diagnostics scoped to the selected row when a row is selected.
Opens portfolio-level warning summary when no row is selected and portfolio warnings exist.

Disabled reason:

No warning refs are available for the current selection.

Secondary Link: Explain Boundary

Label:

Explain boundary

Behavior:

Opens boundary explanation for selected inactive, promoted, archived, deferred, revisit-candidate, unsupported, or out-of-scope rows.
Hidden or disabled for clean active selections unless nearby boundary context is selected.

Primary Action: Continue To Verify Path

The Portfolio Overview may show the primary action inside the selected preview region. If shown here, the control behavior is:

Label:

Continue to verify path

Enabled when:

A path is selected.
The path is active or warning-level.
No blocking diagnostic affects selected-path verification.
Required source support is readable and not malformed.
The selected path is not promoted, inactive, archived, deferred, revisit-candidate, unsupported, unresolved, contradicted, or out of scope.

Disabled reason examples:

Select an active path to continue.
This path has blocking diagnostics. Review them before verification.
Normal active routing is suppressed for promoted paths.
Required selected-path source support is unreadable.

Do not expose copy-next-command, handoff/export, mutation, write-back, or command execution controls.

Copy Requirements

Primary heading:

Portfolio overview

Helper copy:

Scan active and parallel AFPS paths, then choose one to verify.

Source-health warning copy:

Warnings are visible and will carry into verification.

Blocking banner copy:

Some portfolio routes are blocked by source issues. Readable rows remain visible, but unsafe actions are disabled.

Suppressed-route examples:

Normal route suppressed: promoted boundary.
Route blocked: unresolved active ref.
Selection unavailable: required source unreadable.

Avoid:

Tutorial copy.
Marketing language.
Clean command language before verification.
Recommended next command or copyable command text.
Phrases that imply the UI edits source files.

Interaction States

Default Clean Portfolio

Source-health strip shows clean/source-backed state.
Active paths appear first.
Clean active rows have visible Select buttons.
Context and boundary rows remain visible only when source evidence supports them.
Primary action stays disabled until a path is selected.

Warning-Level Portfolio

Source-health strip shows warning status with warning count.
A compact warning explanation appears above grouped rows or inside the source strip.
Affected rows show warning badges.
Warning-level active rows remain selectable when no blocking diagnostic affects verification.
Selected warning context must carry forward to verification.

Partial Source

Source-health strip reads Partial source or equivalent.
Rows derived from partial source carry partial/inferred trust labels.
Actions depending on missing source are disabled with reasons.
The UI avoids stating clean active guidance for partially supported rows.

Multiple Active Paths

Active group shows each active path with comparable row structure.
No path is silently routed as final next work.
One safe active path may be preselected only when source evidence supports it, and the selection remains visibly source-derived and reversible.

Promoted Or Inactive Context

Boundary/context rows remain visibly separate from active rows.
Action is Explain or disabled, not normal verification.
Suppression reason is visible in-row.

Unresolved Active Ref

Show the unresolved ref as a row or warning item; do not drop it.
Use Unresolved and Blocked labels when appropriate.
Action routes to Review or diagnostics, not selected-path verification.

Blocking Portfolio Issue

Show a blocking banner above grouped rows.
Keep readable rows visible.
Disable or suppress unsafe row actions with visible reasons.
If the issue prevents trustworthy overview generation, route to Blocking Diagnostic Summary instead of this resolved overview.

Empty Or No-AFPS

This page should not render as a zero-count normal overview when no AFPS product paths are found. Route to Empty / No-AFPS State.

Loading

This page should not show unresolved skeletons after entering the resolved overview. Loading behavior belongs to Loading / Scan.

Error

For UI rendering failure after a scan result exists:

Show The portfolio overview could not be displayed.
Preserve source-health and diagnostic links if available.
Do not invent replacement path facts.

Offline

Offline status should not block a repo-local overview by itself. If shown, label separately:

Network is offline. Local portfolio data remains available.

Visual And Spatial Rules

Keep the page compact and utilitarian.
Cards and panels use 8px radius or less.
Do not use a landing-page hero, decorative gradients, or illustrative empty dashboard chrome.
Source-health strip is visually first but not oversized.
Count cards are compact, with fixed minimum height to prevent layout shift.
Rows use predictable column-like alignment on desktop.
Warning, blocked, and boundary labels must be visible without row expansion.
Selected row highlight must be clear but restrained; avoid making unselected rows look disabled.
Use more than color to distinguish states: labels, icons, borders, and text.
The page should not read as a one-hue palette; warning/blocked/status accents should be secondary to neutral operational surfaces.
Text inside badges and buttons must fit at mobile sizes without truncating the meaningful status word.

Accessibility Requirements

Main content starts at the source-health strip after the header.
Source-health strip has an accessible name such as Portfolio source health.
Count summary has an accessible name such as Portfolio counts.
Each path group is a labelled region.
Each row is keyboard reachable or contains a keyboard-reachable primary control.
Row controls have programmatic disabled states and visible disabled reasons.
Selected row state is programmatically exposed with aria-selected or equivalent.
Warning and blocked states are announced with severity and count.
Group collapse toggles expose expanded/collapsed state.
Focus order:

Header repository context
Source-health strip and source-health link
Count summary
Portfolio-level warning or blocking banner
Active path group rows and row actions
Context/boundary groups and row actions
Selected preview and primary action, when present
Secondary source, warning, and boundary links

Touch targets for buttons and links are at least 44px high on touch layouts.
Reduced motion disables animated status changes and uses static state changes.
Color-blind safe patterns are required for warning, blocked, active, promoted, and unresolved states.

Data Requirements

Fields this page may consume:

Repository label or path.
Scan completion and freshness timestamp.
Portfolio source-health state.
Parser confidence.
Source confidence.
Active refs count.
Unresolved refs count.
Blocking issue count.
Warning count.
Product path label, ID, scope path, status, boundary kind, pipeline stage, last touched, next safe branch, next skill, suppression reason, trust level, warning IDs, diagnostic refs, and source refs.
Selected path ID and selected row state.

Fields this page must not require:

Full evidence/provenance detail.
Copyable next command.
Handoff/export metadata.
Auth/account data.
Remote sync state.
Production persistence status.
Write-back capability.

Transition Rules

From Loading / Scan with one or more source-backed paths: render Portfolio Overview.
From Loading / Scan with warning-level issues: render Portfolio Overview with warning strip and row warnings preserved.
From Loading / Scan with no AFPS paths: route to Empty / No-AFPS State.
From Loading / Scan with blocking issue that prevents trustworthy rows: route to Blocking Diagnostic Summary.
Selecting a clean or warning-level active row: update selected row highlight and selected preview.
Continuing with a safe selected row: route to selected-path verification with trust and warning context preserved.
Selecting promoted/inactive/out-of-scope context: route to boundary explanation or show selected preview with normal continuation suppressed.
Selecting unresolved/blocked context: route to diagnostics/review or show disabled reason.

Downstream Handoff Constraints

The Portfolio Overview passes source-health summary, path counts, selected path ID, parser confidence, source confidence, trust level, warnings, diagnostic refs, source refs, and suppressed-route reasons into downstream sibling flows.

It does not pass a copy-ready command, final handoff answer, production implementation plan, source mutation request, or account/session state.

The later screen builder should treat this page as the main resolved orientation batch: establish source-health, counts, grouped rows, and desktop selected-preview placement before layering inline selected preview behavior for smaller breakpoints.

Open Risks

If warning badges are too subtle, the branch may optimize speed at the cost of source trust.
If context groups are too prominent, inactive/promoted boundaries may distract from active-path selection.
If suppressed-route reasons are too terse, users may not understand why a visible row cannot continue normally.
If selected preview appears too detailed, the page may absorb selected-path verification and blur sibling-flow boundaries.

---

Page Intermediate: Selected Row Preview Page Spec

Source file: design/afps-tracker/ui-interview-quick-scan-overview/selected-row-preview.md

Selected Row Preview Page Spec

Scope

The Selected Row Preview is the compact confirmation state that appears after an operator selects a product path row in the Quick-Scan Overview branch. It confirms what was selected, preserves trust and warning context, and explains whether Continue to verify path is enabled or disabled.

This surface must not become selected-path verification. It may show label, status, stage, trust level, warning count, diagnostic count, source-confidence summary, and the enabled or disabled reason for continuing. It must not expose copy-next-command behavior, full evidence/provenance detail, repair instructions, write-back controls, command execution, final handoff/export, or implementation sequencing.

Source Evidence

Confirmed brief: design/afps-tracker/_working/ui-interview-quick-scan-overview-brief.md
Whole-branch mockup reference: design/afps-tracker/_working/ui-mockup-quick-scan-overview.html
Parent UX variation: design/afps-tracker/ux-variations-uf-orient-portfolio.md
Parent flow branch: uf-orient-portfolio
Existing intermediate references:
design/afps-tracker/ui-interview-quick-scan-overview/loading-scan.md
design/afps-tracker/ui-interview-quick-scan-overview/portfolio-overview.md

User Goal And Success Condition

The operator should be able to confirm that the intended row is selected and understand the next safe route without opening a full detail page.

Success conditions:

Selected path identity is unmistakable.
Current status, pipeline stage, and source trust are visible.
Warning and diagnostic counts remain visible after selection.
Continue to verify path is enabled only for active or warning-level route-safe paths.
Disabled or suppressed continuation explains the reason in plain language.
Secondary links route to sibling flows without expanding this preview into full verification.

Layout Anatomy

Desktop And Wide Desktop

On desktop, the preview appears in the right column of the Portfolio Overview workspace.

Placement and structure:

Right-side panel, approximately 340-380px wide.
Panel top aligns with the grouped path list top, below any portfolio-level warning or blocking banner.
Selected identity block at the top.
Compact status and trust summary below the identity block.
Warning/diagnostic summary below trust facts.
Primary action block with enabled or disabled reason.
Secondary links at the bottom.

Desktop spacing:

Panel padding: 16-20px.
Section gaps: 14-18px.
Badge rows wrap within the panel instead of overflowing.
Primary action width: full panel width.
The panel may become sticky below the header only when it does not overlap source-health, count summary, or warning banners.

When no row is selected, the panel remains present as an empty-selection prompt so the right column does not jump.

Tablet

At widths below approximately 1040px:

The preview becomes an inline expansion directly below the selected row.
It spans the row list width.
It keeps the same content order as desktop.
It should visually connect to the selected row with a restrained border, inset, or selected-state continuation.
It must not push source-health or count summary below the fold when a user selects a row.

Mobile

At widths below approximately 700px:

The preview appears immediately after the selected row as a compact vertical expansion.
Identity, status, and trust facts stack in single-column order.
Primary action remains at least 44px tall.
Secondary links wrap into stacked text or icon+text buttons.
Long path IDs and scope paths wrap with preserved readability; do not force horizontal scroll.

Component Inventory

Empty Selection Panel

Shown before a row is selected.

Content:

Heading: Select a path
Helper: Choose an active or warning-level path to preview the next verification route.
Optional source reminder: Warnings and source confidence will carry forward.

The empty panel may include a disabled primary action to reserve space:

Label: Continue to verify path
Disabled reason: Select an active path to continue.

Do not show fake selected path data.

Selected Identity Block

Content:

Path label.
Path ID.
Scope path, when available.
Selected-state label: Selected path.
Optional last touched value when already present in the row data.

Rules:

Path label is the most prominent text in the panel.
Path ID and scope path are secondary and wrap safely.
If label is missing but path ID exists, use the ID as the primary visible identifier and show Label unavailable as a warning-level metadata fact.

Compact Status Summary

Fields:

Status or boundary kind.
Pipeline stage.
Next safe branch or next skill, only as routing context.
Trust level.
Parser confidence.
Source confidence.

Display:

Use compact labelled rows or small status blocks.
Preserve exact trust semantics from the row; do not upgrade partial, inferred, or warning-level source to clean language.
Next safe branch is descriptive context, not a copy-ready command.

Warning And Diagnostic Summary

Content:

Warning count.
Diagnostic count.
Highest severity label.
Affected source summary when compact enough.

State labels:

Clean
{n} warnings
Partial source
Blocked
Unresolved
Contradicted
Unreadable source
Malformed source

Rules:

Warning and blocked facts must remain visible without hover.
Use color, icon/shape, and text together.
If there are warnings but continuation is still allowed, state that warnings will carry into verification.
If a diagnostic blocks continuation, show the disabled reason before secondary links.

Primary Action Block

Primary action:

Continue to verify path

Enabled only when:

A path is selected.
The path is active or warning-level.
No blocking diagnostic affects selected-path verification.
Required source support is readable.
The selected path is not promoted, inactive, archived, deferred, revisit-candidate, unsupported, unresolved, contradicted, malformed, unreadable, or out of scope.

Enabled helper copy:

Clean active path: Verification will open with source confidence and path context preserved.
Warning-level active path: Warnings will carry into verification.

Disabled reason examples:

Select an active path to continue.
This path has blocking diagnostics. Review them before verification.
Normal active routing is suppressed for promoted paths.
This inactive path can be explained, but not verified as active work.
Required selected-path source support is unreadable.
This path is unresolved, so verification would not be source-backed.
This path is out of scope for AFPS Tracker.

The disabled reason is visible as text near the disabled action and exposed programmatically.

Secondary Links

Links are contextual and may be hidden when no relevant refs exist.

Inspect Source

Label:

Inspect source

Behavior:

Routes to source/provenance inspection for the selected row.
Carries selected path ID, source refs, trust level, parser confidence, source confidence, warnings, and diagnostic refs.

Disabled reason:

Source refs are unavailable for this selection.

Review Warnings

Label:

Review warnings

Behavior:

Routes to warning or diagnostics inspection scoped to the selected row.
Enabled when warning IDs or diagnostic refs exist.

Disabled reason:

No warning refs are available for this selection.

Explain Boundary

Label:

Explain boundary

Behavior:

Routes promoted, inactive, archived, deferred, revisit-candidate, unsupported, unresolved, or out-of-scope selections to the boundary explanation sibling flow.
Carries boundary kind, suppression reason, source refs, trust level, and warnings.

Visibility:

Show for boundary/context rows.
Hide or disable for clean active selections.

Review Diagnostics

Label:

Review diagnostics

Behavior:

Routes blocked, malformed, unreadable, unresolved, or contradicted selections to diagnostics recovery.
Carries diagnostic refs and affected source paths.

Visibility:

Show when diagnostic refs exist or continuation is blocked by a diagnostic condition.

Control Inventory

Primary Button: Continue To Verify Path

Label:

Continue to verify path

Behavior:

Routes to uf-verify-selected-path.
Passes selected path ID, label, scope path, status, stage, trust level, parser confidence, source confidence, warning IDs, diagnostic refs, source refs, and route-safety state.

Disabled behavior:

Remains focusable only if the design system uses focusable disabled explanatory controls; otherwise place the visible disabled reason immediately after the disabled button.
Never routes when continuation is blocked.

Screen reader names:

Continue to verify {path_label} path
Continue unavailable for {path_label}: {disabled_reason}

Secondary Link Buttons

Labels:

Inspect source
Review warnings
Explain boundary
Review diagnostics

Behavior:

Route to sibling flows only.
Preserve selection context.
Do not mutate source files or execute commands.

Close Or Collapse Control

Desktop:

No close button is required. Selecting a different row replaces the preview.

Tablet/mobile:

A collapse control may be used when inline expansion would make long lists hard to scan.

Label:

Collapse preview

Rules:

Collapsing preview does not clear selected row state unless the user explicitly selects another row.
Expanded/collapsed state must be programmatically exposed.

Copy Requirements

Empty selection:

Heading: Select a path
Helper: Choose an active or warning-level path to preview the next verification route.

Selected path:

Eyebrow: Selected path
Primary action: Continue to verify path
Clean helper: Ready for selected-path verification.
Warning helper: Warnings will carry into verification.
Blocked helper: Verification is blocked until this source issue is reviewed.
Boundary helper: Normal active routing is suppressed for this path.

Avoid:

Recommended next command
Copyable command text
Run
Fix
Update source
Export
Share
Resolve automatically
Any phrase implying source write-back, command execution, or final handoff readiness.

Interaction States

No Selection

Empty Selection Panel is visible.
Primary action is disabled or hidden.
Helper text tells the user to choose an active or warning-level row.
Secondary links are hidden or disabled.

Clean Active Selection

Identity block shows selected path label and ID.
Status summary reads active/source-backed.
Warning summary shows Clean or 0 warnings only when source evidence explicitly supports it.
Primary action is enabled.
Inspect source may be available.
Review warnings, Explain boundary, and Review diagnostics are hidden or disabled unless refs exist.

Warning-Level Active Selection

Warning badge and count are visible.
Primary action may remain enabled if no blocking diagnostic affects verification.
Helper text says warnings will carry into verification.
Review warnings is enabled.
Selection highlight must not look clean.

Partial Or Inferred Source Selection

Source confidence is labelled as partial or inferred.
Actions depending on missing source are disabled with visible reasons.
Primary action is enabled only if selected-path verification can preserve uncertainty without false claims.
Inspect source or Review warnings is available when refs exist.

Promoted Or Inactive Boundary Selection

Boundary badge is visible.
Primary action is disabled.
Disabled reason explains normal active routing suppression.
Explain boundary is the main available secondary route.
The preview must not present the path as active next work.

Unresolved Selection

Unresolved badge is visible.
Primary action is disabled.
Diagnostic or source review route is available when refs exist.
The preview must not invent label, stage, or next-skill facts missing from source.

Blocking Diagnostic Selection

Blocked status is prominent.
Primary action is disabled.
Disabled reason names the blocking category.
Review diagnostics is enabled.
Other readable facts remain visible.

Selection Change

Selecting another row updates panel content without resetting source-health or row-list scroll position.
The previous row loses selected state.
Focus should move predictably to the preview heading or remain on the row control depending on interaction pattern; keyboard users must not lose context.

Loading

This preview should not show selected current-state facts while the current scan is unresolved.
If retained prior selection is shown during Loading / Scan, it must be labelled Prior selection and all current actions remain disabled.

Error

If preview rendering fails while row data remains visible:

Show The selected path preview could not be displayed.
Keep the selected row highlighted only if route-safety facts are still known.
Disable Continue to verify path.
Preserve links to source health or diagnostics when refs exist.

Offline

Offline status does not block this repo-local preview by itself. If shown, label separately:

Network is offline. Local selection context remains available.

Visual And Spatial Rules

Keep the preview subordinate to the Portfolio Overview; it confirms selection but should not dominate the page.
Cards and panels use 8px radius or less.
Use neutral operational surfaces with restrained status accents.
Warning, blocked, boundary, and unresolved states require text labels plus visual treatment.
The selected path label should be prominent but not hero-scale.
Long IDs, paths, and disabled reasons wrap cleanly.
The primary action block should be stable in height so changing warning counts does not cause major layout shift.
Empty and selected states should occupy similar panel width to avoid desktop grid movement.
Inline mobile expansion should not look like a modal or separate page.
Do not use decorative imagery, gradients, large illustrations, or marketing-style panels.

Accessibility Requirements

The preview region has an accessible name such as Selected path preview.
Empty and selected states announce their heading.
The selected row in the list exposes selected state with aria-selected or equivalent.
The preview heading references the selected path label.
Primary action disabled reasons are programmatically associated with the button.
Warning and blocked summaries include severity and count in accessible text.
Secondary links have destination-specific labels, not repeated generic View text.
Keyboard order:

Selected row control in the path list
Preview heading
Status and trust summary
Warning or diagnostic summary
Continue to verify path
Disabled reason, if present
Secondary links
Collapse control on tablet/mobile, if present

Touch targets are at least 44px high on touch layouts.
Reduced motion disables animated panel transitions and uses immediate state replacement.
Color-blind safe patterns are required for warning, blocked, promoted, unresolved, and selected states.
Screen reader labels must distinguish active verification from boundary explanation and diagnostics review.

Data Requirements

Fields this preview may consume:

Selected path ID.
Path label.
Scope path.
Status.
Boundary kind.
Pipeline stage.
Next safe branch.
Next skill.
Trust level.
Parser confidence.
Source confidence.
Warning IDs and warning count.
Diagnostic refs and diagnostic count.
Source refs.
Suppression reason.
Last touched.
Route-safety classification.

Fields this preview must not require:

Full evidence/provenance body.
Copyable next command.
Handoff/export metadata.
Account or collaboration data.
Remote sync state.
Production persistence status.
Source mutation capability.
Repair command content.

Transition Rules

From Portfolio Overview with no selection: show Empty Selection Panel.
Selecting a clean active row: update selected highlight, show clean active preview, enable Continue to verify path.
Selecting a warning-level active row: update selected highlight, show warning summary, enable continuation only if no blocking diagnostic affects verification.
Selecting promoted, inactive, archived, deferred, revisit-candidate, unsupported, or out-of-scope context: show boundary preview and suppress normal continuation.
Selecting unresolved, contradicted, malformed, unreadable, or blocked context: show diagnostic preview and suppress normal continuation.
Activating Continue to verify path: route to selected-path verification with trust and warning context preserved.
Activating Inspect source: route to source/provenance inspection.
Activating Review warnings or Review diagnostics: route to diagnostics or warning inspection.
Activating Explain boundary: route to inactive/promoted boundary explanation.

Downstream Handoff Constraints

The Selected Row Preview may pass selection identity, route-safety classification, trust level, parser confidence, source confidence, warnings, diagnostic refs, source refs, and disabled/suppression reasons to sibling flows.

It does not pass a copy-ready command, final answer, export payload, source mutation request, repair instruction, production implementation plan, account state, or collaboration state.

The later screen builder should treat this state as a layer on top of the Portfolio Overview: desktop right-panel content first, then tablet/mobile inline expansion behavior.

Open Risks

If the preview shows too much detail, it may absorb selected-path verification and weaken sibling-flow boundaries.
If disabled reasons are too terse, users may not understand why a visible row cannot continue.
If warning-level active selections look visually clean, source-trust safety regresses.
If inline mobile expansion is too tall, row scanning may become slower than the Quick-Scan thesis supports.

---

Page Intermediate: Empty / No-AFPS State Page Spec

Source file: design/afps-tracker/ui-interview-quick-scan-overview/empty-no-afps-state.md

Empty / No-AFPS State Page Spec

Scope

The Empty / No-AFPS State appears when the repo-local scan completes and AFPS Tracker cannot find source-backed AFPS product paths for the current repository scope. Its job is to tell the operator exactly what source was checked, preserve diagnostic visibility, and avoid inventing active-route guidance.

This page may show repository identity, checked source locations, scan freshness, no-path result, source-health facts, missing-source diagnostics, and links into diagnostics or source/provenance sibling flows. It must not show a normal zero-count portfolio overview, fabricate active paths, recommend a next command, expose write-back or repair controls, or imply that AFPS Tracker can continue to selected-path verification without source-backed path evidence.

Source Evidence

Confirmed brief: design/afps-tracker/_working/ui-interview-quick-scan-overview-brief.md
Whole-branch mockup reference: design/afps-tracker/_working/ui-mockup-quick-scan-overview.html
Parent UX variation: design/afps-tracker/ux-variations-uf-orient-portfolio.md
Parent flow branch: uf-orient-portfolio
Existing intermediate references:
design/afps-tracker/ui-interview-quick-scan-overview/loading-scan.md
design/afps-tracker/ui-interview-quick-scan-overview/portfolio-overview.md
design/afps-tracker/ui-interview-quick-scan-overview/selected-row-preview.md

User Goal And Success Condition

The operator should understand that the tracker performed a local scan, found no AFPS product paths, and cannot offer a normal active-route path until source artifacts exist or diagnostics are resolved.

Success conditions:

Repository identity and scan freshness are visible.
The page states that no AFPS product paths were found without implying a system failure when the scan was valid.
Checked source locations are named so the result is auditable.
Missing, unreadable, malformed, or unsupported source diagnostics remain visible.
Primary continuation into selected-path verification is absent or disabled with an explicit reason.
Links into source health or diagnostics preserve source refs and diagnostic refs when available.
The empty state does not include copyable command guidance, repair instructions, write-back controls, or fabricated next work.

Layout Anatomy

Desktop And Wide Desktop

Use the same shallow shell as Loading / Scan and Portfolio Overview so the empty result feels like a scan outcome, not a separate marketing-style empty dashboard.

Structure:

Header strip at the top, full width, 64-76px tall.
Main content constrained to approximately 960-1120px, centered inside the same page padding system as the overview.
Source-health strip directly below the header, showing scan completion and no-path source status.
Empty result panel below source health.
Checked source list and diagnostic summary below the result panel.
Secondary actions row below diagnostics.

Desktop spacing:

Main content horizontal padding: 40px on wide desktop, 24px on standard desktop.
Major vertical gaps: 16-22px.
Empty result panel padding: 24-28px.
Source list and diagnostic summary may use a two-column layout when both have enough content.
Keep the page vertically compact enough that source-health, result message, and primary disabled reason are visible above the fold on common laptop screens.

Do not reserve the right-side selected preview column in this state. There is no selected path.

Tablet

At widths below approximately 1040px:

Keep source-health, empty result, checked source list, diagnostics, and secondary actions in one column.
Source-list and diagnostics sections stack.
Secondary actions wrap to multiple rows if needed.
Keep disabled primary-route reason adjacent to the empty result message.

Mobile

At widths below approximately 700px:

Header stacks product title, repository label, and scan freshness.
Source-health strip becomes stacked status blocks.
Empty result panel becomes a compact vertical section with no decorative illustration requirement.
Checked source paths wrap naturally and may use monospace styling for path fragments.
Secondary actions are full-width or stacked with 44px minimum touch targets.
Long diagnostic refs wrap without horizontal scrolling.

Component Inventory

Content:

Product title: AFPS Tracker
Repository label: Repository: {repo_path_or_label}
Scan freshness: Local scan complete {relative_time} or Local scan complete

Rules:

Keep language repo-local.
Avoid sync, upload, connected, or remote-service framing.
Do not show a selected path label.

Source-Health Strip

Purpose: make the empty result auditable before the page explains the absence of paths.

Cells:

Source health: clean empty, warning, partial, or blocked.
Parser confidence: high, medium, low, unknown.
Source confidence: source-backed empty result, partial, missing, unreadable, malformed, unsupported.
Checked refs: count and unresolved count.
Diagnostic issues: warning and blocking counts.

State rules:

Clean empty result should read as a valid scan result, not as success for active work.
Missing or partial source must be labelled as Partial source or Missing source, not clean.
Blocked source must route to Blocking Diagnostic Summary when no trustworthy empty result can be produced.
Use color, label text, and icon/shape variation together; do not rely on color alone.

Empty Result Panel

Content:

Heading: No AFPS product paths found
Helper: AFPS Tracker scanned the local source artifacts for this repository and did not find source-backed product paths.
Disabled-route reason: Selected-path verification is unavailable until an AFPS product path is found.
Optional locality note: This result is based on repo-local files, not a network sync.

Visual rules:

The heading is prominent but not hero-scale.
The panel may use a small neutral icon if the existing design system has one; it must not use a large decorative illustration.
The disabled-route reason should be close to the primary action area or the place where a primary action would normally appear.

Checked Source List

Purpose: show what was actually inspected.

Content:

Checked source path labels, such as research/.progress.yaml when present.
Product-path scoped research or design artifacts when the scanner checked them.
Flow-tree or alignment refs when they were part of discovery.
Source status for each item: checked, missing, unreadable, malformed, unsupported, skipped, or not present.

Rules:

Do not show paths that were not evaluated unless clearly labelled as expected-but-not-found.
Missing expected files may appear as diagnostic rows, not as active paths.
If no source refs were produced, show Source refs unavailable and route any detail control to disabled state.

Diagnostic Summary

Purpose: preserve troubleshooting context without turning this page into recovery instructions.

Content:

Warning count.
Blocking issue count.
Highest severity.
Affected source paths or refs.
Short diagnostic label.

Diagnostic examples:

No active product path refs found.
Product path manifest missing.
Scoped product path directory not found.
Source unreadable.
Source malformed.
Unsupported path state.

Rules:

If diagnostics explain why AFPS paths could not be found, show them visibly below the empty message.
If diagnostics are blocking and prevent trust in the no-path result, this page should hand off to Blocking Diagnostic Summary instead.
Avoid repair-command text and copyable shell snippets.

Disabled Primary Route Block

The page may reserve the primary-action location to explain why no normal route is available.

Label:

Continue to verify path

State:

Disabled or absent.

Disabled reason:

No AFPS product path is available to verify.

Rules:

If shown, the disabled button must be paired with visible helper text.
Do not allow selection or continuation from this page.
Do not use the primary button for diagnostics; diagnostics are secondary actions.

Secondary Actions

Secondary actions must be clearly subordinate to the empty result and source-health facts.

Inspect Source Health

Label:

Inspect source health

Behavior:

Routes to the source/provenance sibling flow when source refs exist.
Carries repository label, checked refs, source-health state, parser confidence, source confidence, unresolved refs, warning refs, and diagnostic refs.

Disabled reason:

Source health details are unavailable because source refs were not produced.

Review Diagnostics

Label:

Review diagnostics

Behavior:

Routes to diagnostics recovery or Blocking Diagnostic Summary when diagnostic refs exist.
Carries affected source paths, highest severity, blocking count, warning count, and diagnostic refs.

Disabled reason:

No diagnostic refs are available for this scan.

Return To Scan

Label:

Scan again

Behavior:

Re-runs or visually restarts the local scan in prototype scope only when the prototype supports this interaction.
Keeps the page in repo-local language and does not imply a file watcher or background sync.

Disabled reason:

Rescan is not available in this prototype.

Rules:

Scan again is optional for the prototype and must not mutate source files.
Do not show Create AFPS path, Initialize AFPS, or command-copy actions in this branch.

Copy Requirements

Primary copy:

Heading: No AFPS product paths found
Helper: AFPS Tracker scanned the local source artifacts for this repository and did not find source-backed product paths.
Disabled-route reason: Selected-path verification is unavailable until an AFPS product path is found.

Source copy:

Checked local sources
Source refs unavailable
This result is based on repo-local files.

Diagnostic copy:

Diagnostics
No diagnostic refs are available for this scan.
Some source files could not be checked. Review diagnostics before trusting the empty result.

Avoid:

Everything is set up
No projects yet
Create your first project
Recommended next command
Copyable shell commands
Repair instructions
Marketing or onboarding copy
Language that implies the UI can write source artifacts

Interaction States

Clean Empty Result

Source-health strip shows a completed, source-backed empty result.
Empty result panel states no AFPS product paths were found.
Checked source list shows inspected refs.
Diagnostics section may show zero warning/blocking count only when those counts are source-derived.
Continue to verify path is absent or disabled with No AFPS product path is available to verify.

Missing Source

Source-health strip reads Missing source or Partial source.
Checked source list identifies missing expected refs.
Diagnostic summary explains which expected source was absent.
Normal active routing remains unavailable.
Review diagnostics is enabled when diagnostic refs exist.

Partial Source

Source-health strip reads Partial source.
Empty result copy clarifies that AFPS paths were not found in the source that could be checked.
Any unavailable or skipped refs are shown in the checked source list.
Avoid claiming the repository has no AFPS paths with full certainty.

Unreadable Or Malformed Source

Source-health strip shows warning or blocked state depending on severity.
Diagnostic summary shows affected source paths.
If a trustworthy empty result cannot be produced, route to Blocking Diagnostic Summary.
If the page remains visible, the disabled route reason must mention source trust.

Unsupported Or Out-Of-Scope Repository

Empty result panel may state that no AFPS product paths were found in the supported repo scope.
Diagnostic summary identifies unsupported or out-of-scope source facts.
Secondary action should favor Inspect source health or Review diagnostics.
Do not show normal active-route continuation.

Loading

The Empty / No-AFPS State must not appear while the scan is unresolved. Loading behavior belongs to Loading / Scan.

Blocking

When blocking source issues prevent AFPS Tracker from safely deciding whether paths exist, route to Blocking Diagnostic Summary instead of presenting this as a valid empty result.

Error

For UI rendering failure after an empty scan result exists:

Show The no-AFPS result could not be displayed.
Preserve source-health and diagnostic links if available.
Do not fabricate path facts.

Offline

Offline status should not invalidate a repo-local empty result by itself. If shown, label separately:

Network is offline. Local source scanning does not require network access.

Visual And Spatial Rules

Keep the state compact, factual, and source-auditable.
Cards and panels use 8px radius or less.
Do not use a landing-page hero, oversized illustration, decorative gradient, or onboarding-style empty project prompt.
The source-health strip remains visually first.
The empty result panel is the clearest element but should not overpower diagnostics.
Checked source and diagnostics sections should be visibly connected to the empty result.
Disabled action styling must not look like a secondary available route.
Text inside buttons, badges, and status cells must fit at mobile sizes.
Long source paths wrap with readable line breaks.
Use neutral surfaces with status accents; avoid a one-hue palette.
Warning, missing, partial, blocked, and unsupported states use labels plus icons or shape, not color alone.

Accessibility Requirements

Main content starts at the source-health strip after the header.
Source-health strip has an accessible name such as Portfolio source health.
Empty result panel has a heading that announces the no-path result.
Checked source list is a labelled region, such as Checked local sources.
Diagnostic summary is a labelled region, such as No-AFPS diagnostics.
Disabled primary route, if present, exposes a programmatic disabled state and visible disabled reason.
Secondary action controls have accessible names that include the action target when useful.
Warning, missing, partial, blocked, and unsupported states are announced with severity and count when known.
Focus order:

Header repository context
Source-health strip and source-health link
Empty result panel
Disabled primary route reason, when present
Checked source list
Diagnostic summary
Secondary actions

Touch targets for buttons and links are at least 44px high on touch layouts.
Reduced motion disables animated scan-result transitions.
Color-blind safe patterns are required for clean empty, missing, partial, warning, blocked, and unsupported states.
Screen readers should not hear fabricated row counts or path labels when no paths exist.

Data Requirements

Fields this page may consume:

Repository label or path.
Scan completion and freshness timestamp.
Portfolio source-health state.
Parser confidence.
Source confidence.
Checked source refs and statuses.
Expected source refs when known.
Unresolved refs count.
Warning count.
Blocking issue count.
Highest diagnostic severity.
Diagnostic refs.
Affected source paths.
Empty result confidence.
Unsupported or out-of-scope reason.

Fields this page must not require:

Product path label, ID, or scope path for a fabricated row.
Selected path ID.
Full evidence/provenance detail.
Copyable next command.
Handoff/export metadata.
Auth/account data.
Remote sync state.
Production persistence status.
Write-back capability.

Transition Rules

From Loading / Scan with a source-backed zero-path result: render Empty / No-AFPS State.
From Loading / Scan with missing or partial source but enough evidence to explain no found paths: render Empty / No-AFPS State with missing/partial diagnostics visible.
From Loading / Scan with blocking issue that prevents a trustworthy empty result: route to Blocking Diagnostic Summary.
From Empty / No-AFPS State to Inspect Source Health: carry checked refs, source-health state, parser confidence, source confidence, unresolved refs, warning refs, and diagnostic refs.
From Empty / No-AFPS State to Review Diagnostics: carry affected source paths, highest severity, warning count, blocking count, and diagnostic refs.
From Empty / No-AFPS State to Scan Again: return to Loading / Scan only when the prototype supports a local rescan interaction.
Do not transition from this page to Selected Row Preview or selected-path verification because no source-backed selected path exists.

---

Page Intermediate: Blocking Diagnostic Summary Page Spec

Source file: design/afps-tracker/ui-interview-quick-scan-overview/blocking-diagnostic-summary.md

Blocking Diagnostic Summary Page Spec

Scope

The Blocking Diagnostic Summary appears when source conditions make normal quick-scan routing unsafe. Its job is to interrupt false confidence, name the blocking source facts, preserve any readable portfolio context, and disable or suppress unsafe actions with explicit reasons.

This surface may show repository identity, scan freshness, portfolio-level source health, affected source paths or refs, blocking categories, warning counts, readable rows, suppressed-route reasons, and secondary links into diagnostics, source health, provenance, or boundary explanation sibling flows. It must not expose repair commands, write-back controls, copy-next-command behavior, command execution, final handoff/export, account/collaboration controls, or production implementation sequencing.

Source Evidence

Confirmed brief: design/afps-tracker/_working/ui-interview-quick-scan-overview-brief.md
Whole-branch mockup reference: design/afps-tracker/_working/ui-mockup-quick-scan-overview.html
Parent UX variation: design/afps-tracker/ux-variations-uf-orient-portfolio.md
Parent flow branch: uf-orient-portfolio
Existing intermediate references:
design/afps-tracker/ui-interview-quick-scan-overview/loading-scan.md
design/afps-tracker/ui-interview-quick-scan-overview/portfolio-overview.md
design/afps-tracker/ui-interview-quick-scan-overview/selected-row-preview.md
design/afps-tracker/ui-interview-quick-scan-overview/empty-no-afps-state.md

User Goal And Success Condition

The operator should understand that AFPS Tracker found blocking source conditions, see which source facts are affected, and still use any readable context without mistaking it for route-safe active work.

Success conditions:

The blocking condition is visible before any path row or continuation control.
Affected source files, path refs, or manifest refs are named when available.
Blocking categories are described in source-trust language, not generic app-error language.
Readable rows remain visible when they can be safely shown.
Normal Continue to verify path behavior is disabled or suppressed with an explicit reason.
Secondary actions route to diagnostics, source health, provenance, or boundary explanation without becoming repair instructions.
The page distinguishes blocking source facts from non-blocking warnings.
The page does not fabricate active path status, trust level, next skill, or command guidance.

Layout Anatomy

Desktop And Wide Desktop

Use the same shallow shell as the Portfolio Overview so the operator can keep orientation while the blocking issue interrupts unsafe continuation.

Structure:

Header strip at the top, full width, 64-76px tall.
Main content constrained to approximately 1360px, centered on very wide screens.
Blocking banner directly below the header and above the source-health strip.
Source-health strip below the banner, with blocked state prominent.
Two-column diagnostic workspace:

Left column: readable grouped rows or source summary.
Right column: blocking diagnostic panel and suppressed action explanation.

Optional affected-source table below the workspace when multiple refs are involved.
Secondary action row below diagnostics.

Desktop spacing:

Main content horizontal padding: 40px on wide desktop, 24px on standard desktop.
Major vertical gaps: 16-22px.
Workspace grid: minmax(0, 1fr) 360px, matching the Portfolio Overview selected-preview column.
Banner padding: 16-20px with dense text and no oversized hero treatment.
Blocking diagnostic panel padding: 16-20px.
Rows remain approximately 72-88px tall when readable portfolio rows can be shown.
Keep the banner, source-health strip, and primary disabled reason visible above the fold on common laptop screens.

The diagnostic panel may become sticky below the header only when it will not overlap the blocking banner or source-health strip. If the blocking explanation is long, prefer normal page scroll over a nested panel scroll.

Tablet

At widths below approximately 1040px:

Collapse the diagnostic workspace to one column.
Keep the blocking banner first, source-health second, then diagnostic panel, then readable rows.
Move suppressed-route explanation next to the diagnostic panel instead of below every row.
Readable rows use the same responsive list anatomy as Portfolio Overview.
Avoid horizontal scrolling for affected-source data; convert source tables to stacked key-value rows when needed.

Mobile

At widths below approximately 700px:

Header stacks product title, repository label, and scan freshness.
Blocking banner becomes a compact alert section with heading, severity, affected count, and short reason.
Source-health strip becomes stacked status blocks.
Diagnostic panel and affected-source refs stack vertically.
Readable rows become compact list items with visible blocked/warning badges.
Primary disabled action or suppressed-route reason is full width and close to the diagnostic explanation.
Long source paths, path IDs, and diagnostic refs wrap naturally with readable line breaks; no horizontal table is required.
Touch targets for secondary actions are at least 44px high.

Component Inventory

Content:

Product title: AFPS Tracker
Repository label: Repository: {repo_path_or_label}
Scan freshness: Local scan completed with blocking diagnostics or Local scan blocked
Optional source timestamp when known.

Rules:

Keep language repo-local.
Avoid sync, upload, connected, server error, or remote-service framing.
Do not show a selected active path as the primary page title.

Purpose: interrupt the quick path before the user scans rows or acts on selected-path routing.

Default content:

Heading: Blocking diagnostics found
Summary: AFPS Tracker found source issues that prevent normal active-path routing. Readable context remains visible, but unsafe actions are disabled.
Affected count: {n} blocking issues
Warning count when present: {m} warnings
Highest severity label.
First affected source path or ref, if compact enough.

Variations:

Unreadable required source: Required source could not be read.
Malformed source: A required source artifact is malformed.
Contradicted source: Source artifacts disagree about this path state.
Unresolved ref: A referenced product path could not be resolved.
Unsupported scope: This source state is outside AFPS Tracker's supported scope.
Out-of-scope path: Normal active routing is suppressed for this out-of-scope path.

Rules:

The banner uses warning/error text, icon or shape treatment, and color together.
The banner must not include repair commands or copyable shell text.
The banner should offer only secondary routes such as Review diagnostics or Inspect source health.
The banner does not replace row-level badges; both portfolio-level and row-level blocking facts remain visible.

Source-Health Strip

Purpose: show the blocked source-trust envelope before row details.

Cells:

Source health: blocked, partial, contradicted, unreadable, malformed, unsupported.
Parser confidence: high, medium, low, unknown.
Source confidence: source-backed partial, missing, contradicted, unresolved, unreadable.
Checked refs: count and unresolved count.
Blocking issues: count and warning count.

State rules:

Blocked state is visually strongest but still uses concise operational styling.
Partial source must not read as clean.
Contradicted source must not be summarized as a generic warning if it blocks route safety.
Unknown confidence should be labelled Unknown, not hidden.
Counts must be source-derived; do not show fabricated zeroes for categories that were not evaluated.

Blocking Diagnostic Panel

Desktop location: right column.

Tablet/mobile location: directly after the source-health strip.

Content:

Panel heading: Why normal routing is blocked
Blocking category.
Affected source path or ref.
Affected path ID or label when source-backed.
Highest severity.
Disabled or suppressed route reason.
Short note explaining what remains safe to inspect.

Example disabled reasons:

Continue is disabled because required source support is unreadable.
Continue is disabled because source artifacts contradict this path's active state.
Continue is disabled because the selected path ref is unresolved.
Normal active routing is suppressed for this promoted or inactive path.
Selected-path verification is unavailable until source trust is restored.

Rules:

The panel explains route safety, not implementation repair.
It may include a compact list of affected refs, but full evidence/provenance detail belongs to sibling flows.
It must make clear whether readable context is partial, prior, or current.
It should not use success styling even if some rows remain readable.

Readable Context Rows

Purpose: preserve orientation when some portfolio data can still be trusted.

Content per row:

Path label or source-backed fallback ID.
Path ID.
Scope path when available.
Status or boundary badge.
Pipeline stage when source-backed.
Trust level.
Warning count.
Blocking badge or suppressed-route reason.
Row-level action: Review, Inspect, Explain, or disabled Select.

Rules:

Rows with blocking diagnostics cannot show normal active continuation.
Clean-looking rows may remain visible only when their own source facts are readable and not contradicted.
A row may show Readable context when it is visible for orientation but not route-safe.
Missing label, stage, or next skill facts should be labelled unavailable rather than inferred.
Warning and blocked badges must remain visible without hover.
If no rows are trustworthy, replace row area with a source summary instead of fabricated rows.

Affected Source List

Purpose: make the diagnostic auditable without exposing full provenance detail.

Content:

Source path or ref.
Source status: unreadable, malformed, contradicted, unresolved, unsupported, missing, skipped, or blocked.
Affected path ID when known.
Blocking category.
Diagnostic ref.
Last checked timestamp or scan phase when available.

Rules:

Use a table on desktop only when it remains readable.
On tablet/mobile, render each source item as a stacked key-value block.
Do not include raw file contents.
Do not include repair commands or write-back controls.
If refs are unavailable, show Affected source refs unavailable and disable source-detail routes with a visible reason.

Suppressed Primary Route Block

Primary route label:

Continue to verify path

State:

Disabled or absent when blocking diagnostics affect selected-path verification.

Visible disabled reason:

Continue is unavailable while blocking diagnostics affect source trust.

Rules:

If the disabled button is shown, it must be paired with visible helper text and programmatic disabled state.
The disabled control must not look like a secondary available route.
Do not repurpose the primary action as Review diagnostics; diagnostics remain secondary.
When no selected path exists, explain both missing selection and blocking source state.

Secondary Actions

Secondary actions are subordinate to the blocking explanation and preserve diagnostic context.

Review Diagnostics

Label:

Review diagnostics

Behavior:

Routes to diagnostics recovery scoped to the blocking issue.
Carries diagnostic refs, affected source paths, affected path IDs, severity, warning count, blocking count, parser confidence, source confidence, and suppressed-route reasons.

Disabled reason:

No diagnostic refs are available for this blocked scan.

Inspect Source Health

Label:

Inspect source health

Behavior:

Routes to source/provenance inspection for checked refs.
Carries checked refs, unresolved refs, source-health state, parser confidence, source confidence, diagnostic refs, and warning refs.

Disabled reason:

Source refs are unavailable for this blocked scan.

Inspect Readable Source

Label:

Inspect readable source

Behavior:

Routes to source/provenance inspection only for refs that were read successfully.
Carries readable source refs, source-backed row IDs, trust level, and warning refs.

Visibility:

Show only when some source refs are readable.

Disabled reason:

No readable source refs are available.

Explain Boundary

Label:

Explain boundary

Behavior:

Routes promoted, inactive, archived, deferred, revisit-candidate, unsupported, unresolved, or out-of-scope facts to the boundary explanation sibling flow.
Carries boundary kind, source refs, suppression reason, trust level, warnings, and diagnostic refs.

Visibility:

Show when the blocking issue is a boundary or scope condition.
Hide when the issue is only malformed, unreadable, or contradicted source.

Control Inventory

Disabled Primary Button: Continue To Verify Path

Label:

Continue to verify path

Disabled behavior:

Does not route while blocking diagnostics affect selected-path verification.
Exposes the disabled reason near the button and programmatically.
Remains focusable only if the design system supports focusable disabled explanatory controls; otherwise place the disabled reason directly after the button.

Screen reader names:

Continue to verify path unavailable: blocking diagnostics affect source trust
Continue unavailable for {path_label}: {disabled_reason}

Row Review Button

Labels:

Review
Review diagnostics

Behavior:

Opens row-scoped diagnostic recovery or source review.
Preserves row ID, source refs, diagnostic refs, warning refs, trust level, and suppression reason.
Does not select the row for normal verification.

Disabled reason:

Review is unavailable because diagnostic refs are missing.

Row Inspect Link

Label:

Inspect source

Behavior:

Opens source/provenance sibling flow for readable source refs.
Does not expose full evidence in this summary page.
Does not mutate source.

Disabled reason:

Source refs are unavailable for this row.

Boundary Explanation Link

Label:

Explain boundary

Behavior:

Opens boundary explanation for promoted, inactive, archived, deferred, revisit-candidate, unsupported, unresolved, or out-of-scope rows.

Disabled reason:

Boundary details are unavailable because source refs are missing.

Group Collapse Toggle

Label:

Collapse readable context
Expand readable context

Rules:

Optional for long readable-row groups.
Never hides the blocking banner, source-health strip, or diagnostic panel.
Collapsed state is programmatically exposed.
Defaults expanded when any row-level blocking issue is present.

Copy Requirements

Primary copy:

Heading: Blocking diagnostics found
Summary: AFPS Tracker found source issues that prevent normal active-path routing. Readable context remains visible, but unsafe actions are disabled.
Disabled-route reason: Continue is unavailable while blocking diagnostics affect source trust.

Diagnostic copy:

Why normal routing is blocked
Affected source
Blocking issue
Readable context
Route suppressed
Source refs unavailable

Row copy:

Readable context only
Selection blocked
Route blocked
Normal active routing suppressed
Warnings remain visible

Avoid:

Recommended next command
Copyable shell commands
Run
Fix
Repair automatically
Resolve now
Update source
Write back
Export
Share
Everything is safe
Any phrase implying command execution, source mutation, final handoff readiness, or full evidence review inside this page.

Interaction States

Blocking With Readable Rows

Blocking banner appears above source-health.
Source-health strip shows blocked or partial source state.
Readable rows remain visible with Readable context only or row-level suppression labels.
Normal row selection and Continue to verify path are disabled.
Review diagnostics, Inspect source health, or Inspect readable source are available when refs exist.

Blocking With No Trustworthy Rows

Blocking banner appears above source-health.
Row area is replaced by a source summary or affected-source list.
No selected preview is shown.
Primary continuation is absent or disabled with visible reason.
Secondary action favors Review diagnostics.

Unreadable Required Source

Source-health strip reads Unreadable source or Blocked.
Affected source list names unreadable path or Affected source refs unavailable.
Rows depending on the unreadable source are hidden, disabled, or labelled unavailable.
Normal active routing remains unavailable.

Malformed Source

Source-health strip reads Malformed source.
Diagnostic panel names the malformed source artifact and affected path ref when known.
Do not parse partial row facts into confident labels unless the data is source-backed outside the malformed artifact.
Review diagnostics is the primary secondary action.

Contradicted Source

Source-health strip reads Contradicted source.
Diagnostic panel states that source artifacts disagree about route safety or path state.
Any affected row shows Contradicted and cannot be selected for normal verification.
Do not choose one source as canonical on this page.

Unresolved Ref

Source-health strip shows unresolved ref count.
Affected source list names the unresolved ref when available.
Row label falls back to source-backed ID only when that ID exists.
Continue to verify path is disabled because verification would not be source-backed.

Boundary Or Scope Block

Blocking banner may read as suppressed active routing rather than malformed source.
Row shows boundary kind, such as promoted, inactive, archived, deferred, revisit-candidate, unsupported, or out of scope.
Primary continuation is disabled.
Explain boundary is the main secondary route when boundary details exist.

Warning-Level But Not Blocking

This page should not appear for warning-only conditions. Warning-only states belong in Portfolio Overview and Selected Row Preview with visible warning badges and enabled continuation when route-safe.

If a warning escalates during the scan:

Replace warning-only overview with Blocking Diagnostic Summary only when route safety becomes blocked.
Preserve warning refs alongside blocking refs.

Loading

Blocking Diagnostic Summary should not appear until the scan knows a blocking condition exists. Early source-access failures during scan may appear as the Loading / Scan early diagnostic banner first.

Error

If the diagnostic summary itself cannot render while source-health facts exist:

Show Blocking diagnostics could not be displayed.
Keep source-health strip visible when available.
Disable Continue to verify path.
Preserve Inspect source health when refs exist.

Offline

Offline network state does not itself create a blocking diagnostic for repo-local AFPS scanning. If shown, label separately:

Network is offline. Local diagnostic context remains available.

Visual And Spatial Rules

The page should feel like an operational interruption, not a full error landing page.
The blocking banner is prominent but compact; avoid hero-scale type.
Cards and panels use 8px radius or less.
Use neutral surfaces with distinct status accents for blocked, warning, partial, unresolved, and boundary states.
Do not rely on red alone; include labels, icons or shape, and severity text.
The source-health strip remains visually before row context.
Readable rows must look less actionable than route-safe Portfolio Overview rows.
Disabled primary action styling must be clearly unavailable and paired with explanatory copy.
Long source paths and diagnostic refs wrap cleanly.
Text inside badges and buttons must fit at mobile sizes.
Avoid decorative images, gradients, large illustrations, or marketing-style empty/error layouts.
Do not use nested cards for the banner, diagnostic panel, affected source list, or rows.
Dynamic warning and blocking counts should not cause major layout shifts.

Accessibility Requirements

The blocking banner has an alert role or equivalent announcement pattern appropriate to the design system.
The banner heading is the first meaningful content after the header.
Source-health strip has an accessible name such as Portfolio source health.
Blocking diagnostic panel has an accessible name such as Blocking diagnostic summary.
Affected source list is a labelled region or table with clear row and column labels.
Disabled primary route exposes both disabled state and visible disabled reason.
Row-level blocked, warning, boundary, unresolved, and partial states include severity and count in accessible text.
Secondary links have destination-specific labels, not repeated generic View text.
Keyboard order:

Header repository context
Blocking banner
Review diagnostics or banner secondary action, when present
Source-health strip
Blocking diagnostic panel
Disabled primary route and disabled reason
Readable context rows or source summary
Row-level review/inspect/explain links
Affected source list
Secondary action row

Focus must not jump to a disabled continuation control when the page appears.
Touch targets are at least 44px high on touch layouts.
Reduced motion disables animated alert transitions and uses immediate state replacement.
Color-blind safe patterns are required for blocked, warning, partial, unresolved, contradicted, and boundary states.
Screen reader labels must distinguish normal active verification from diagnostic review and boundary explanation.

Data Requirements

Fields this page may consume:

Repository label or path.
Scan completion and freshness timestamp.
Portfolio source-health state.
Parser confidence.
Source confidence.
Checked source refs and statuses.
Readable source refs.
Unreadable, missing, malformed, unsupported, contradicted, unresolved, and skipped refs.
Warning count.
Blocking issue count.
Highest diagnostic severity.
Diagnostic refs.
Affected source paths.
Affected path IDs and labels when source-backed.
Boundary kind.
Suppression reason.
Route-safety classification.
Trust level for readable rows.
Pipeline stage for source-backed readable rows.

Fields this page must not require:

Full evidence/provenance body.
Copyable next command.
Handoff/export metadata.
Auth/account data.
Collaboration data.
Remote sync state.
Production persistence status.
Source mutation capability.
Repair command content.
Final implementation plan.

Transition Rules

From Loading / Scan with blocking source issue: render Blocking Diagnostic Summary once the blocking condition is known.
From Portfolio Overview when portfolio-level blocking issue appears: show Blocking Diagnostic Summary while preserving readable rows when safe.
From Portfolio Overview when selected row has blocking diagnostic: show row-scoped Blocking Diagnostic Summary or selected preview blocked state according to prototype scope; normal continuation remains disabled.
From Empty / No-AFPS State when a trustworthy empty result cannot be produced: route to Blocking Diagnostic Summary.
From Blocking Diagnostic Summary to Review Diagnostics: carry diagnostic refs, affected source paths, affected path IDs, severity, warning count, blocking count, parser confidence, source confidence, and suppression reasons.
From Blocking Diagnostic Summary to Inspect Source Health: carry checked refs, readable refs, unresolved refs, source-health state, parser confidence, source confidence, diagnostic refs, and warning refs.
From Blocking Diagnostic Summary to Inspect Readable Source: carry only readable source refs and source-backed row IDs.
From Blocking Diagnostic Summary to Explain Boundary: carry boundary kind, source refs, suppression reason, trust level, warnings, and diagnostic refs.
Do not transition from this page to selected-path verification while blocking diagnostics affect route safety.
Do not transition from this page to copy-next-command, handoff/export, source repair, write-back, or production implementation planning.

Downstream Handoff Constraints

The Blocking Diagnostic Summary may pass source-health state, route-safety classification, parser confidence, source confidence, warning refs, diagnostic refs, affected source paths, affected path IDs, readable source refs, boundary kind, suppression reason, and disabled-route reasons to sibling flows.

It does not pass a copy-ready command, final answer, export payload, source mutation request, repair instruction, production implementation plan, account state, collaboration state, or full evidence/provenance body.

The later screen builder should treat this as the route-safety interruption for Quick-Scan Overview: banner and source-health first, readable context second, disabled primary continuation with explicit reason, and diagnostics/source/boundary routes as secondary exits only.

Visual Mockup Reference

The whole-branch visual mockup is available at design/afps-tracker/_working/ui-mockup-quick-scan-overview.html. It is referenced here as source evidence and should be reviewed alongside this packet when judging layout, hierarchy, controls, copy, and state treatment.

This alignment page does not embed the mockup as an iframe; the review substance is rendered directly above, and the mockup remains a supplemental repo-local artifact.

Review Gates

Approve the Quick-Scan Overview UI packet for canonical write? Approve: write the canonical UI packet/interview log and update the flow-tree decision after agent review. Revise: keep this in review and apply the feedback below. Reject: do not promote this UI experiment branch. Notes or required changes

Compile Responses

Use this after answering the gate. Partial feedback is valid; final approval requires the approve option and no unresolved revision notes.

Supplemental Source View

Raw markdown is included only as a supplemental audit view. The primary review surface is the rendered packet above.

# Preliminary UI Interview Research: Quick-Scan Overview

Interview provenance: live-ui-interview

Invocation: `$ui-interview quick-scan-overview`

Product path: `research/afps-tracker`

Topic: `quick-scan-overview`

Status: pre-approval review packet

Alignment page: `alignment/ui-interview-quick-scan-overview.html`

## Interview Stage

This is the chunked-mode assemble-and-approve session for `$ui-interview quick-scan-overview` in full UI branch-review mode. The UI Assumptions Manifest and open decisions were confirmed in `research/afps-tracker/_working/interrogation-ui-interview-r1.yaml`, the shared context brief was written at `design/afps-tracker/_working/ui-interview-quick-scan-overview-brief.md`, and the five page-specific intermediates under `design/afps-tracker/ui-interview-quick-scan-overview/` now exist. This packet is not a canonical UI branch packet yet; it is the complete proposed review content for the single binding alignment gate.

## Proposed Canonical Destinations

- UI branch packet: `design/afps-tracker/ui-quick-scan-overview.md`
- UI interview log: `design/afps-tracker/ui-quick-scan-overview-interview.md`
- Flow-tree manifest update after approval: `design/afps-tracker/flow-tree-afps-tracker.yaml`
- Working packet archive after approval: `docs/history/archive/YYYY-MM-DD/HHMMSS/research/afps-tracker/_working/preliminary-ui-interview-research.md`

## Source Evidence

- Shared context brief: `design/afps-tracker/_working/ui-interview-quick-scan-overview-brief.md`
- Whole-branch visual mockup: `design/afps-tracker/_working/ui-mockup-quick-scan-overview.html`
- Interrogation sidecar: `research/afps-tracker/_working/interrogation-ui-interview-r1.yaml`
- Parent flow: `design/afps-tracker/user-flow-afps-tracker.md`
- Parent UX variation: `design/afps-tracker/ux-variations-uf-orient-portfolio.md`
- Flow-tree manifest: `design/afps-tracker/flow-tree-afps-tracker.yaml`
- Page intermediates:
- Loading / Scan Page Spec: `design/afps-tracker/ui-interview-quick-scan-overview/loading-scan.md`
- Portfolio Overview Page Spec: `design/afps-tracker/ui-interview-quick-scan-overview/portfolio-overview.md`
- Selected Row Preview Page Spec: `design/afps-tracker/ui-interview-quick-scan-overview/selected-row-preview.md`
- Empty / No-AFPS State Page Spec: `design/afps-tracker/ui-interview-quick-scan-overview/empty-no-afps-state.md`
- Blocking Diagnostic Summary Page Spec: `design/afps-tracker/ui-interview-quick-scan-overview/blocking-diagnostic-summary.md`

## Branch Investigation And Decision Record

Parent user-flow branch: `uf-orient-portfolio`

Selected UX variation branch: `quick-scan-overview`

Touched sibling flows: selected-path verification, evidence/provenance inspection, diagnostics recovery, inactive/promoted boundary explanation, handoff/export. These remain outside the Quick-Scan Overview branch except as secondary links or carried context.

Competing or coordinating sibling UX variations: trust-first source health, diagnostics-first recovery, portfolio-map grouping, and command/resume-first orientation from the approved `ux-variations` packet.

Proposed branch decision: approve this UI experiment as the first Quick-Scan Overview UI branch after review, provided the alignment page receives final compiled YAML approval. Until approval, this remains a review-state packet and must not write canonical UI specs or flow-tree decisions.

## Prototype-First Boundary

First clickable journey: scan repo-local AFPS artifacts, show a quick portfolio overview, select a route-safe active or warning-level path, and hand off to selected-path verification with trust and warning context preserved.

Experiment route map: Loading / Scan -> Portfolio Overview -> Selected Row Preview, with alternate outcomes to Empty / No-AFPS State and Blocking Diagnostic Summary.

Fixture or fake data: allowed for scan status, path counts, grouped rows, source-health states, warning counts, diagnostic refs, and selected path facts.

Visually mocked infrastructure only: repo-local scanning, source parsers, diagnostics source refs, trust/confidence derivation, and downstream sibling-flow routes.

Deferred production infrastructure: file watcher, persistent storage, source mutation/write-back, auth, accounts, collaboration, deployment, analytics, command execution, copy-next-command, final handoff/export.

Evidence required before implementation planning promotes deferred infrastructure: prototype evaluation showing operators can orient quickly without losing source-trust visibility, and UAT evidence that warning/blocked/suppressed states are understood before continuation.

## Coverage Checkpoint

- Pages covered: Loading / Scan, Portfolio Overview, Selected Row Preview, Empty / No-AFPS State, Blocking Diagnostic Summary.
- Components covered: header shell, source-health strip, count summary, grouped path rows, selected preview, empty result panel, diagnostic banner/panel, affected-source list, disabled primary route block, secondary source/diagnostic/boundary links.
- Controls covered: row select, explain, review, group collapse, source-health link, warnings link, primary Continue to verify path, inspect source, review diagnostics, scan again, collapse preview.
- States covered: loading, slow loading, prior-state retained, early warning, early blocking, clean portfolio, warning-level portfolio, partial source, multiple active paths, promoted/inactive context, unresolved active refs, clean empty, missing source, unreadable/malformed source, unsupported/out-of-scope, blocking with readable rows, blocking with no trustworthy rows, error, offline.
- Responsive coverage: desktop/wide desktop, tablet under about 1040px, mobile under about 700px, no horizontal table requirement for first value.
- Accessibility coverage: labelled regions, keyboard order, disabled reasons, warning severity announcements, touch targets, reduced motion, color-blind safe state treatment, screen reader names.
- Unresolved risks: warning prominence could be too subtle; context groups could distract from active selection; selected preview could absorb verification if over-detailed; disabled/suppressed reasons must be explicit enough to preserve trust.


---

# UI Interview Brief: Quick-Scan Overview

Invocation: `$ui-interview quick-scan-overview`

Product path: `research/afps-tracker`

Parent user-flow branch: `uf-orient-portfolio`

Selected UX variation branch: `quick-scan-overview`

Visual mockup: `design/afps-tracker/_working/ui-mockup-quick-scan-overview.html`

Interrogation sidecar: `research/afps-tracker/_working/interrogation-ui-interview-r1.yaml`

## Confirmed UI Assumptions Manifest

| ID | Source | Decision | Resolved meaning |
| --- | --- | --- | --- |
| product-user | [from spec] | Confirmed | Primary user is an AFPS power user / AI workflow operator returning to repo-local AFPS state after context loss, session restart, compaction, handoff, or branch-state review. |
| branch-boundary | [from artifact] | Confirmed | This UI branch covers only orientation to the product portfolio: open tracker, scan active and parallel paths, and select one path for deeper verification. |
| coordination | [from artifact] | Confirmed | Selected-path verification, evidence/provenance inspection, diagnostics recovery, handoff/export, and inactive/promoted boundary explanation stay sibling flows. |
| pages-routes | [from artifact] | Confirmed | The branch has five screen/state surfaces: Loading / Scan, Portfolio Overview, Selected Row Preview, Empty / No-AFPS State, and Blocking Diagnostic Summary. |
| hierarchy | [from research] | Confirmed | First-screen hierarchy is source-health strip, count summary, grouped path list, row-level warnings, then selected preview. |
| controls-states | [from codebase] | Confirmed | Controls and states preserve source-native trust envelopes, warning visibility, disabled reasons, and normal-route suppression rules from the approved model. |
| visual-stack | [inferred] | Confirmed | Use a restrained, utilitarian web UI mockup with static/local data and no production storage, auth, networking, or write-back implementation. |

## Confirmed Open Decisions

Warnings in the first screen: use a persistent source-health strip plus row-level warning badges. Blocking issues interrupt the quick path with a banner. Non-blocking warnings stay visible without taking over row scanning.

Selected-path preview depth: show label, status, stage, trust level, warning count, and the enabled or disabled reason for `Continue to verify path`. Exclude copy-next-command and full evidence/provenance detail from the orientation screen.

Default layout: desktop uses a top source-health strip, count summary, grouped path list, and right-side selected preview. Tablet and mobile move the selected preview into an inline expansion below the selected row.

## Scope Boundaries

The branch may show portfolio-level source health, path counts, grouped rows, row-level warning badges, selected row highlight, a compact selected-row preview, suppressed-route reasons, and secondary links into sibling flows.

The branch must not expose primary copy-next-command behavior, full evidence/provenance detail, write-back controls, command execution, account/collaboration controls, storage architecture, file watcher behavior, or implementation sequencing.

## Page Inventory

### Loading / Scan

Purpose: communicate that AFPS Tracker is reading repo-local source files. It shows the repository label, scan status, source-health/count skeletons, grouped-row skeletons, and any early source-access diagnostic placeholder. Loading must not imply network activity. Prior state, if retained later, must be labelled as prior until the current scan completes.

### Portfolio Overview

Purpose: let the operator orient and select. It shows the header, source-health strip, portfolio count summary, grouped active/parallel/context rows, row select affordances, warning badges, trust badges, suppressed-route reasons, and secondary source-health links.

### Selected Row Preview

Purpose: confirm selection without turning orientation into selected-path verification. On desktop it appears as a right-side preview. On tablet and mobile it becomes an inline expansion below the selected row. It shows only compact selection facts and the enabled/disabled reason for `Continue to verify path`.

### Empty / No-AFPS State

Purpose: avoid fabricated guidance. It names the source checked, explains that no AFPS product paths were found, exposes relevant diagnostics, and avoids active-route guidance when source artifacts do not support it.

### Blocking Diagnostic Summary

Purpose: preserve orientation while preventing false confidence. It interrupts the quick path with a banner, names affected source files/path refs, keeps readable rows visible, and disables or suppresses unsafe actions with explicit reasons.

## Global Shell And Navigation Decisions

The first UI proposal uses a shallow shell: repository title, source scan freshness, source-health strip, count summary, grouped path list, and selected preview. No global sidebar is required for this branch. Secondary navigation is limited to source health, row diagnostics, boundary explanation, evidence inspection, and provenance inspection as links into sibling flows.

The primary action is `Continue to verify path`. It is enabled only when a selected path is active or warning-level and not blocked by contradiction, unreadable required source, promoted boundary, out-of-scope boundary, unresolved ref, or malformed source. The action carries selected path ID, trust level, parser confidence, source confidence, warnings, and diagnostic refs forward.

## Evaluation Criteria

First-value clarity: the operator can identify active and parallel paths within a few seconds.

Source-trust visibility: warning, partial, blocked, unresolved, inactive, and promoted states are visible before selection.

Branch-selection speed: the user can select a path without opening diagnostics first when source state is clean or warning-level.

Boundary safety: inactive, promoted, archived, deferred, revisit-candidate, unresolved, contradicted, unsupported, and out-of-scope paths do not appear as normal active routes.

Preview discipline: selected preview remains compact and does not absorb selected-path verification, evidence/provenance inspection, or handoff/export behavior.

Responsive viability: desktop side preview becomes an inline expansion on tablet/mobile without requiring a horizontal table for first value.

## Carried Branch Decision Context

The approved UX variation set recommends `quick-scan-overview` as the first UI branch under `uf-orient-portfolio`. This brief does not approve the UI experiment. It only carries confirmed assumptions and the whole-branch mockup into chunked page-specific specification sessions.


---

# Page Intermediate: Loading / Scan Page Spec

Source file: `design/afps-tracker/ui-interview-quick-scan-overview/loading-scan.md`

# Loading / Scan Page Spec

## Scope

The Loading / Scan page is the first transient surface in the Quick-Scan Overview branch. It communicates that AFPS Tracker is reading repo-local AFPS source artifacts, preserves trust boundaries while the current scan is unresolved, and prepares the operator for the Portfolio Overview, Empty / No-AFPS State, or Blocking Diagnostic Summary.

This page must not imply network activity, background account sync, production storage, file watcher behavior, command execution, write-back, or final handoff readiness. It may show retained prior scan information only when every retained value is labelled as prior state until the current scan completes.

## Source Evidence

- Confirmed brief: `design/afps-tracker/_working/ui-interview-quick-scan-overview-brief.md`
- Whole-branch mockup reference: `design/afps-tracker/_working/ui-mockup-quick-scan-overview.html`
- Parent UX variation: `design/afps-tracker/ux-variations-uf-orient-portfolio.md`
- Parent flow branch: `uf-orient-portfolio`

## User Goal And Success Condition

The operator should understand, within a second or two, that AFPS Tracker is scanning local repository artifacts and has not yet produced current portfolio guidance.

Success conditions:

- Repository identity is visible.
- Scan status is explicit and local-source framed.
- Placeholder structure previews the same information architecture as the resolved overview.
- Early source-access problems can appear without fabricating portfolio results.
- Prior retained data, if shown, cannot be confused for the current scan result.

## Layout Anatomy

### Desktop And Wide Desktop

Use the same shallow shell as the resolved overview so the page does not reflow dramatically after scan completion:

1. Header strip at the top, full width, 64-76px tall.
2. Main content constrained to the same max width as the overview, approximately 1360px.
3. Source-health placeholder strip directly below the header.
4. Count-summary skeleton row below the source strip.
5. Main workspace grid with grouped-row skeletons on the left and a scan-status / prior-state panel on the right.
6. Optional early diagnostic banner above the source-health placeholder when source access fails before path parsing begins.

Desktop grid:

- Main content horizontal padding: 40px on wide desktop, 24px on standard desktop.
- Vertical gap between major regions: 16-22px.
- Workspace grid: `minmax(0, 1fr) 360px`, matching the overview preview width.
- Right panel remains sticky only after enough vertical content exists; during short loading states it can stay static to avoid awkward scroll behavior.

### Tablet

At widths below approximately 1040px:

- Collapse workspace to one column.
- Keep the source-health placeholder before the count placeholders.
- Move the scan-status / prior-state panel below the grouped-row skeletons.
- Avoid horizontal scrolling for row skeletons.

### Mobile

At widths below approximately 700px:

- Header stacks repository label and scan state.
- Source-health placeholder becomes a vertical list.
- Count placeholders stack one per row.
- Grouped-row skeletons use card-like vertical anatomy, not table columns.
- Right-side scan-status panel becomes an inline section after the first grouped skeleton block.

## Component Inventory

### Header

Content:

- Product title: `AFPS Tracker`
- Repository label: `Repository: {repo_path_or_label}`
- Scan state indicator: animated or static status dot plus text.

Default scan text:

- `Scanning repo-local AFPS artifacts...`

If a scan is taking longer than expected:

- `Still scanning repo-local AFPS artifacts...`

The header must not say `syncing`, `uploading`, `connecting`, or any phrase that implies a remote service.

### Source-Health Skeleton Strip

Purpose: reserve the resolved source-health position while avoiding claims before scan completion.

Cells:

- Source health
- Parser confidence
- Source confidence
- Unresolved refs
- Blocking issues

Each cell uses:

- A small uppercase label.
- A skeleton value bar or `Checking...` text.
- No clean/warning/blocked color until the scan knows the value.

If an early source-access diagnostic exists, this strip may show a warning or blocked state only for the affected source-access fact, with unresolved fields still shown as checking.

### Count Summary Skeletons

Purpose: reserve portfolio count positions.

Cards:

- Active paths
- Parallel context
- Inactive/context paths
- Promoted boundary

Each card shows a skeleton number block and label. Do not show zero counts while the scan is incomplete unless the scan has definitively reached the no-AFPS state.

### Grouped Row Skeletons

Purpose: preview the row-scanning structure used by the Portfolio Overview.

Groups:

- Active Paths
- Parallel / Context Paths
- Inactive And Boundary Context, only if prior state or scan metadata justifies showing the group placeholder.

Each group contains 2-3 row skeletons with stable column positions:

- Path title / path ID block
- Status badge placeholder
- Stage placeholder
- Next safe branch placeholder
- Warning badge placeholder
- Select action placeholder

The Select placeholder must be visibly disabled and must not be clickable while the current scan is unresolved.

### Scan-Status / Prior-State Panel

Desktop location: right column.

Tablet/mobile location: inline below the grouped skeletons.

Content:

- Heading: `Reading local sources`
- Current source list, if available:
  - `research/.progress.yaml`
  - Product-path scoped research/design artifacts when known
  - Alignment or design-tree manifest refs when known
- Current scan phase:
  - `Locating product paths`
  - `Reading path status`
  - `Checking warnings`
  - `Preparing overview`
- Prior-state notice when retained values are displayed.

Prior-state notice copy:

- `Prior scan data may be shown for orientation only. Current actions stay disabled until this scan completes.`

### Early Diagnostic Banner

Show this only when the scan has already detected a source-access issue before portfolio rows are trustworthy.

Warning copy:

- `Some source files are still being checked. The overview will keep actions disabled until source trust is known.`

Blocking copy:

- `AFPS Tracker cannot finish the local scan yet. Review the source issue before using portfolio guidance.`

The banner links only to a diagnostics sibling flow placeholder when such a route exists in the prototype. It must not expose repair commands on this page.

## Control Inventory

### Disabled Row Select Placeholders

Label:

- `Select`

State:

- Disabled while loading.

Disabled reason:

- `Selection is unavailable until the current source scan completes.`

Screen reader name:

- `Select path unavailable until scan completes`

### Secondary Link: Source Health

Label:

- `Source health`

Behavior:

- If the prototype includes the sibling source-health route, this navigates to source/provenance or diagnostic inspection.
- During loading, it may be visible but disabled until diagnostic refs exist.

Disabled reason:

- `Source health details are not available until source refs are known.`

### Secondary Link: Diagnostics

Label:

- `Diagnostics`

Behavior:

- Enabled only when an early warning or blocked source-access issue exists.
- Routes to the diagnostics recovery sibling flow, carrying diagnostic refs.

Disabled reason:

- `No diagnostic refs are available yet.`

### Primary Action Placeholder

The page may reserve space for `Continue to verify path`, but the action must be disabled or hidden while loading.

Disabled reason:

- `Choose a path after the scan completes.`

Do not show copy-next-command, export, handoff, write-back, or command execution controls.

## Copy Requirements

Use concise, source-native language:

- Heading: `Scanning portfolio`
- Helper: `Reading repo-local AFPS artifacts before showing active paths.`
- Locality note: `No network activity is required for this scan.`
- Prior-state label: `Prior scan`
- Current-state label: `Current scan`
- Completion transition text, if needed: `Scan complete. Preparing overview...`

Avoid:

- Tutorial copy.
- Marketing language.
- System architecture promises.
- Phrases that imply cloud sync, background automation, or mutation of source files.

## Interaction States

### Default Loading

- Header scan dot uses subtle motion or a static pulsing treatment.
- Source-health strip, count cards, and rows show skeletons.
- Select and continue actions are disabled.
- No warning or clean state is implied before known.

### Slow Loading

Trigger when scan exceeds the prototype's chosen loading threshold.

- Replace default helper with `Still scanning repo-local AFPS artifacts...`
- Keep skeleton layout stable.
- Show source list or current phase if available.
- Do not create a retry action unless the underlying prototype actually supports retry.

### Prior State Retained

- Prior values can appear muted below skeletons or inside the right panel.
- Every retained value must be labelled `Prior scan`.
- Any action derived from prior state remains disabled.
- Current scan skeletons remain visually primary.

### Early Warning

- Show non-blocking banner.
- Keep scan progress visible.
- Diagnostics link may become enabled when diagnostic refs exist.
- Row placeholders remain disabled.

### Early Blocking Issue

- Show blocking banner above the source-health strip.
- Keep any readable source facts visible.
- Suppress or disable path-selection and continue actions with explicit reasons.
- Route next resolved surface to Blocking Diagnostic Summary instead of Portfolio Overview when the scan cannot produce trustworthy path rows.

### Empty Completion Transition

When the scan completes and no AFPS paths exist:

- Do not briefly show zero counts on this page as if it were the overview.
- Transition directly to Empty / No-AFPS State.
- If an intermediate text is needed, use `No AFPS product paths found in checked sources.`

### Error

For unrecoverable UI-level rendering errors, show a compact error region within the shell:

- `The scan result could not be displayed.`
- Include a diagnostics link only if diagnostic refs exist.
- Do not invent source facts.

### Offline

Offline status should not block a local scan unless the app shell itself requires unavailable assets. If shown, label it separately:

- `Network is offline. Local repository scan can continue.`

## Visual And Spatial Rules

- Keep cards and panels at 8px radius or less.
- Use restrained neutral surfaces with clear warning and blocked accents only when those states are known.
- Skeleton blocks should be low-contrast and distinct from actual values.
- Loading motion must be subtle, not central to the page.
- The source-health placeholder must remain first in the content hierarchy.
- Count cards should maintain fixed minimum heights so the completion transition does not jump.
- Row skeletons should match resolved row height closely, approximately 68-76px on desktop.
- Mobile row skeletons may expand vertically but should keep consistent spacing.

## Accessibility Requirements

- Main loading region uses `aria-busy="true"` while scan is unresolved.
- Scan status text is exposed through a polite live region.
- Blocking diagnostic banner uses assertive announcement only when it appears after initial render.
- Skeleton-only content must have accessible labels; do not rely on visual shimmer.
- Disabled controls must include programmatic disabled state and visible disabled reasons.
- Keyboard order:
  1. Header repository context
  2. Source-health / diagnostic banner
  3. Count summary placeholders
  4. Grouped skeleton sections
  5. Scan-status / prior-state panel
  6. Enabled diagnostics/source links, if any
- Touch targets for any enabled link or button must be at least 44px high.
- Respect reduced motion by disabling shimmer/pulse animation and using static skeletons.
- Color cannot be the only warning indicator; include text labels such as `Warning` and `Blocked` when those states are known.

## Data Requirements

Fields this page may consume:

- Repository label or path.
- Scan status: pending, scanning, slow, warning, blocked, complete.
- Current scan phase.
- Source file labels being checked.
- Optional prior scan timestamp and prior summary values.
- Early diagnostic refs, severity, affected source, and summary.

Fields this page must not require:

- Full evidence/provenance detail.
- Copyable next command.
- Handoff/export metadata.
- Auth/account data.
- Remote sync state.
- Production persistence status.

## Transition Rules

- On successful scan with one or more paths: transition to Portfolio Overview.
- On successful scan with no AFPS paths: transition to Empty / No-AFPS State.
- On blocking source issue: transition to Blocking Diagnostic Summary or keep the banner visible until the user follows diagnostics.
- On warning-level issue: continue to Portfolio Overview with warning counts and row-level warning badges preserved.
- If exactly one safe active path is known after completion, the next page may preselect it, but this loading page must not preselect during scan.

## Downstream Handoff Constraints

The Loading / Scan page passes only scan status, source-health summary, diagnostic refs, and prior-state labels forward. It does not pass selected path context because selection cannot happen here.

The later screen builder should treat this as one flow-step batch that establishes the shell and loading placeholders before resolved overview content is layered on top.

## Open Risks

- If prior scan values are too visually prominent, users may mistake stale data for current guidance.
- If loading lasts long enough to need retry, the retry behavior must be model-backed before a button appears.
- If early diagnostics are available, the page must show enough issue context to preserve trust without absorbing the full diagnostics recovery flow.

---

# Page Intermediate: Portfolio Overview Page Spec

Source file: `design/afps-tracker/ui-interview-quick-scan-overview/portfolio-overview.md`

# Portfolio Overview Page Spec

## Scope

The Portfolio Overview page is the primary first-value surface for the Quick-Scan Overview branch. It appears after the repo-local scan has produced a trustworthy enough portfolio snapshot and lets an AFPS operator orient to active, parallel, inactive/context, promoted, unresolved, and warning-level paths without reading raw source files.

This page may show portfolio-level source health, path counts, grouped rows, row warnings, trust badges, suppressed-route reasons, selected-row highlight, and compact links into sibling flows. It must not absorb selected-path verification, evidence/provenance inspection, diagnostics recovery, handoff/export, copy-next-command behavior, write-back controls, account/collaboration features, production storage, or command execution.

## Source Evidence

- Confirmed brief: `design/afps-tracker/_working/ui-interview-quick-scan-overview-brief.md`
- Whole-branch mockup reference: `design/afps-tracker/_working/ui-mockup-quick-scan-overview.html`
- Parent UX variation: `design/afps-tracker/ux-variations-uf-orient-portfolio.md`
- Parent flow branch: `uf-orient-portfolio`
- Existing intermediate style reference: `design/afps-tracker/ui-interview-quick-scan-overview/loading-scan.md`

## User Goal And Success Condition

The operator should identify active and parallel product paths, understand source trust and warnings, and select one path for deeper verification within a few seconds.

Success conditions:

- Repository identity and scan freshness are visible.
- Source health appears before path selection.
- Active paths appear first and are scannable without expanding every row.
- Warning, partial, blocked, unresolved, inactive, promoted, archived, deferred, revisit-candidate, unsupported, and out-of-scope states are visible before action.
- Selectable active or warning-level rows can be chosen without forcing diagnostic triage first.
- Unsafe rows show explicit suppressed-route reasons instead of normal active continuation.
- The page can pass a selected active/warning path into selected-path verification with trust, parser confidence, source confidence, warnings, and diagnostic refs preserved.

## Layout Anatomy

### Desktop And Wide Desktop

Use a shallow, operational dashboard layout with the source-trust envelope above the path list:

1. Header strip at the top, full width, 64-76px tall.
2. Main content constrained to approximately 1360px, centered on very wide screens.
3. Source-health strip directly below the header.
4. Portfolio count summary below source health.
5. Workspace grid with grouped path rows on the left and selected preview on the right.
6. Optional warning or blocking banner above grouped rows when portfolio-level issues affect route safety.

Desktop spacing:

- Main content horizontal padding: 40px on wide desktop, 24px on standard desktop.
- Major vertical gaps: 16-22px.
- Workspace grid: `minmax(0, 1fr) 360px`.
- Left column minimum usable width: 680px.
- Right preview width: 340-380px.
- Row height: approximately 72-88px for dense desktop rows.
- Group gap: 16px.

The selected preview may be sticky below the header once content scrolls, but it must not cover source-health or warning banners. If the viewport is too short, keep the panel static and let the page scroll normally.

### Tablet

At widths below approximately 1040px:

- Collapse the workspace to one column.
- Keep source-health and counts above rows.
- Replace the right-side preview with an inline selected-row expansion beneath the selected row.
- Keep row columns for label/status/stage/warnings/select, while moving secondary metadata into a second line.
- Avoid horizontal scrolling.

### Mobile

At widths below approximately 700px:

- Header stacks product title, repository label, and scan freshness.
- Source-health strip becomes stacked status blocks.
- Count summary becomes a two-column grid or single-column stack on narrow phones.
- Grouped rows become compact list items with visible badges and a 44px minimum select affordance.
- Selected preview appears immediately below the selected row.
- Group metadata and secondary links collapse into concise text rows.
- No horizontal table is required for first value.

## Component Inventory

### Header

Content:

- Product title: `AFPS Tracker`
- Repository label: `Repository: {repo_path_or_label}`
- Scan freshness: `Scan complete {relative_time}` or `Local scan complete`
- Optional source timestamp when known.

The header must frame the page as repo-local orientation. Avoid `sync`, `upload`, `connected`, or other remote-service language.

### Source-Health Strip

Purpose: make source trust visible before any row is selected.

Cells:

- Source health: clean, warning, partial, blocked.
- Parser confidence: high, medium, low, unknown.
- Source confidence: source-backed, inferred, partial, missing, contradicted.
- Active refs: count and unresolved count.
- Blocking issues: count and warning count.

Each cell contains:

- A concise label.
- A value.
- Optional source file or diagnostic ref summary when needed.

State rules:

- Clean state may use a restrained positive accent but still shows source labels.
- Warning state uses text plus color, not color alone.
- Blocked state becomes visually prominent and must be paired with disabled/suppressed route reasons in rows.
- Partial state must not read as clean; use `Partial source` or `Warning-level source`.

### Portfolio Count Summary

Cards:

- `Active paths`
- `Parallel context`
- `Inactive/context paths`
- `Promoted boundary`

Optional cards when source evidence supports them:

- `Unresolved refs`
- `Blocked routes`
- `Out-of-scope`

Each card shows a number, label, and short state hint when useful. Counts must be source-derived; do not show fabricated zeroes for categories the source did not evaluate.

### Grouped Path List

Default group order:

1. Active Paths
2. Parallel And Boundary Context
3. Inactive / Deferred / Archived Context, only when present and useful
4. Unresolved Or Blocked Refs, either as its own group or visibly inside the affected group

Group header content:

- Group title.
- One-line group meta, such as `Selectable rows preserve warning context into verification`.
- Optional group-level warning count.
- Optional collapse toggle only for non-primary context groups.

Active Paths should be open by default. Context groups may be open by default when they contain warnings, promoted boundaries, unresolved refs, or suppressed-route facts that matter to the first-value read.

### Product-Path Row

Canonical row content:

- Path label.
- Path ID.
- Scope path.
- Status or boundary badge.
- Pipeline stage.
- Next safe branch, next skill, or suppression reason.
- Last touched, when available.
- Trust level.
- Warning or diagnostic count.
- Select, explain, review, or disabled action.

Variations:

- Clean active row: selectable, trust badge reads clean/source-backed.
- Warning active row: selectable only if no blocking diagnostic affects selected-path verification; warning count remains visible.
- Parallel/context row: can be selectable for explanation or preview, but normal active continuation is suppressed unless model marks it active/warning-level.
- Promoted or inactive row: action is `Explain`, not `Continue`.
- Unresolved row: action is `Review` or disabled; normal active route blocked.
- Contradicted, malformed, unreadable, unsupported, out-of-scope, or blocked row: disabled/suppressed with visible reason.

Rows must not hide warnings behind hover-only controls. The row should remain understandable with no pointer hover.

### Warning And Diagnostic Badges

Badge labels:

- `Clean`
- `{n} warnings`
- `Blocked`
- `Unresolved`
- `Partial source`
- `Promoted`
- `Inactive`
- `Archived`
- `Deferred`
- `Out of scope`

Badges use color, label text, and icon or shape variation where available. Warning and blocked badges must expose accessible names with severity and count.

### Selected Preview Region

On desktop, the selected preview lives in the right column. On tablet and mobile, it belongs to the Selected Row Preview page/state as an inline expansion under the selected row.

Portfolio Overview owns the placement and row-selection trigger, but the detailed selected preview content is specified in `selected-row-preview.md`. The overview must reserve enough space and selected context for that page/state without expanding into full verification.

## Control Inventory

### Row Select Button

Labels:

- `Select`
- `Selected`

Behavior:

- Selects an active or warning-level path for compact preview.
- Updates selected-row highlight.
- Enables `Continue to verify path` only when selected path is route-safe.
- Preserves selected path ID, trust level, parser confidence, source confidence, warning IDs, and diagnostic refs.

Disabled reason examples:

- `Selection is unavailable because this path is unresolved.`
- `Selection is unavailable because required source support is unreadable.`
- `Selection is unavailable because this path is promoted and normal active routing is suppressed.`

Screen reader names:

- `Select {path_label} path`
- `{path_label} path selected`
- `Select unavailable for {path_label}: {disabled_reason}`

### Explain Button

Label:

- `Explain`

Behavior:

- Routes inactive, promoted, archived, deferred, revisit-candidate, unsupported, or out-of-scope rows to the boundary explanation sibling flow.
- Carries path ID, boundary kind, source refs, trust level, warnings, and suppression reason.

This control must not look like normal active continuation.

### Review Button

Label:

- `Review`

Behavior:

- Routes unresolved, malformed, contradicted, unreadable, or blocked refs to diagnostics recovery or source-health inspection.
- Carries diagnostic refs and affected source paths.

### Group Collapse Toggle

Use only for secondary context groups when the list becomes long.

Labels:

- `Show {group_name}`
- `Hide {group_name}`

Rules:

- Active Paths should not be collapsed by default.
- Groups containing blocking issues, unresolved active refs, or promoted boundary warnings should remain open or show a prominent count when collapsed.
- Toggle state must be keyboard accessible and announced with expanded/collapsed state.

### Secondary Link: Inspect Source Health

Label:

- `Inspect source health`

Behavior:

- Opens portfolio-level source/provenance or diagnostics sibling flow.
- Carries source-health summary, parser confidence, source confidence, unresolved refs, and diagnostic refs.

Disabled or hidden only when no source refs exist. If disabled, show: `Source health details are unavailable because source refs were not produced.`

### Secondary Link: Review Warnings

Label:

- `Review warnings`

Behavior:

- Opens warnings or diagnostics scoped to the selected row when a row is selected.
- Opens portfolio-level warning summary when no row is selected and portfolio warnings exist.

Disabled reason:

- `No warning refs are available for the current selection.`

### Secondary Link: Explain Boundary

Label:

- `Explain boundary`

Behavior:

- Opens boundary explanation for selected inactive, promoted, archived, deferred, revisit-candidate, unsupported, or out-of-scope rows.
- Hidden or disabled for clean active selections unless nearby boundary context is selected.

### Primary Action: Continue To Verify Path

The Portfolio Overview may show the primary action inside the selected preview region. If shown here, the control behavior is:

Label:

- `Continue to verify path`

Enabled when:

- A path is selected.
- The path is active or warning-level.
- No blocking diagnostic affects selected-path verification.
- Required source support is readable and not malformed.
- The selected path is not promoted, inactive, archived, deferred, revisit-candidate, unsupported, unresolved, contradicted, or out of scope.

Disabled reason examples:

- `Select an active path to continue.`
- `This path has blocking diagnostics. Review them before verification.`
- `Normal active routing is suppressed for promoted paths.`
- `Required selected-path source support is unreadable.`

Do not expose copy-next-command, handoff/export, mutation, write-back, or command execution controls.

## Copy Requirements

Primary heading:

- `Portfolio overview`

Helper copy:

- `Scan active and parallel AFPS paths, then choose one to verify.`

Source-health warning copy:

- `Warnings are visible and will carry into verification.`

Blocking banner copy:

- `Some portfolio routes are blocked by source issues. Readable rows remain visible, but unsafe actions are disabled.`

Suppressed-route examples:

- `Normal route suppressed: promoted boundary.`
- `Route blocked: unresolved active ref.`
- `Selection unavailable: required source unreadable.`

Avoid:

- Tutorial copy.
- Marketing language.
- Clean command language before verification.
- `Recommended next command` or copyable command text.
- Phrases that imply the UI edits source files.

## Interaction States

### Default Clean Portfolio

- Source-health strip shows clean/source-backed state.
- Active paths appear first.
- Clean active rows have visible `Select` buttons.
- Context and boundary rows remain visible only when source evidence supports them.
- Primary action stays disabled until a path is selected.

### Warning-Level Portfolio

- Source-health strip shows warning status with warning count.
- A compact warning explanation appears above grouped rows or inside the source strip.
- Affected rows show warning badges.
- Warning-level active rows remain selectable when no blocking diagnostic affects verification.
- Selected warning context must carry forward to verification.

### Partial Source

- Source-health strip reads `Partial source` or equivalent.
- Rows derived from partial source carry partial/inferred trust labels.
- Actions depending on missing source are disabled with reasons.
- The UI avoids stating clean active guidance for partially supported rows.

### Multiple Active Paths

- Active group shows each active path with comparable row structure.
- No path is silently routed as final next work.
- One safe active path may be preselected only when source evidence supports it, and the selection remains visibly source-derived and reversible.

### Promoted Or Inactive Context

- Boundary/context rows remain visibly separate from active rows.
- Action is `Explain` or disabled, not normal verification.
- Suppression reason is visible in-row.

### Unresolved Active Ref

- Show the unresolved ref as a row or warning item; do not drop it.
- Use `Unresolved` and `Blocked` labels when appropriate.
- Action routes to `Review` or diagnostics, not selected-path verification.

### Blocking Portfolio Issue

- Show a blocking banner above grouped rows.
- Keep readable rows visible.
- Disable or suppress unsafe row actions with visible reasons.
- If the issue prevents trustworthy overview generation, route to Blocking Diagnostic Summary instead of this resolved overview.

### Empty Or No-AFPS

This page should not render as a zero-count normal overview when no AFPS product paths are found. Route to Empty / No-AFPS State.

### Loading

This page should not show unresolved skeletons after entering the resolved overview. Loading behavior belongs to Loading / Scan.

### Error

For UI rendering failure after a scan result exists:

- Show `The portfolio overview could not be displayed.`
- Preserve source-health and diagnostic links if available.
- Do not invent replacement path facts.

### Offline

Offline status should not block a repo-local overview by itself. If shown, label separately:

- `Network is offline. Local portfolio data remains available.`

## Visual And Spatial Rules

- Keep the page compact and utilitarian.
- Cards and panels use 8px radius or less.
- Do not use a landing-page hero, decorative gradients, or illustrative empty dashboard chrome.
- Source-health strip is visually first but not oversized.
- Count cards are compact, with fixed minimum height to prevent layout shift.
- Rows use predictable column-like alignment on desktop.
- Warning, blocked, and boundary labels must be visible without row expansion.
- Selected row highlight must be clear but restrained; avoid making unselected rows look disabled.
- Use more than color to distinguish states: labels, icons, borders, and text.
- The page should not read as a one-hue palette; warning/blocked/status accents should be secondary to neutral operational surfaces.
- Text inside badges and buttons must fit at mobile sizes without truncating the meaningful status word.

## Accessibility Requirements

- Main content starts at the source-health strip after the header.
- Source-health strip has an accessible name such as `Portfolio source health`.
- Count summary has an accessible name such as `Portfolio counts`.
- Each path group is a labelled region.
- Each row is keyboard reachable or contains a keyboard-reachable primary control.
- Row controls have programmatic disabled states and visible disabled reasons.
- Selected row state is programmatically exposed with `aria-selected` or equivalent.
- Warning and blocked states are announced with severity and count.
- Group collapse toggles expose expanded/collapsed state.
- Focus order:
  1. Header repository context
  2. Source-health strip and source-health link
  3. Count summary
  4. Portfolio-level warning or blocking banner
  5. Active path group rows and row actions
  6. Context/boundary groups and row actions
  7. Selected preview and primary action, when present
  8. Secondary source, warning, and boundary links
- Touch targets for buttons and links are at least 44px high on touch layouts.
- Reduced motion disables animated status changes and uses static state changes.
- Color-blind safe patterns are required for warning, blocked, active, promoted, and unresolved states.

## Data Requirements

Fields this page may consume:

- Repository label or path.
- Scan completion and freshness timestamp.
- Portfolio source-health state.
- Parser confidence.
- Source confidence.
- Active refs count.
- Unresolved refs count.
- Blocking issue count.
- Warning count.
- Product path label, ID, scope path, status, boundary kind, pipeline stage, last touched, next safe branch, next skill, suppression reason, trust level, warning IDs, diagnostic refs, and source refs.
- Selected path ID and selected row state.

Fields this page must not require:

- Full evidence/provenance detail.
- Copyable next command.
- Handoff/export metadata.
- Auth/account data.
- Remote sync state.
- Production persistence status.
- Write-back capability.

## Transition Rules

- From Loading / Scan with one or more source-backed paths: render Portfolio Overview.
- From Loading / Scan with warning-level issues: render Portfolio Overview with warning strip and row warnings preserved.
- From Loading / Scan with no AFPS paths: route to Empty / No-AFPS State.
- From Loading / Scan with blocking issue that prevents trustworthy rows: route to Blocking Diagnostic Summary.
- Selecting a clean or warning-level active row: update selected row highlight and selected preview.
- Continuing with a safe selected row: route to selected-path verification with trust and warning context preserved.
- Selecting promoted/inactive/out-of-scope context: route to boundary explanation or show selected preview with normal continuation suppressed.
- Selecting unresolved/blocked context: route to diagnostics/review or show disabled reason.

## Downstream Handoff Constraints

The Portfolio Overview passes source-health summary, path counts, selected path ID, parser confidence, source confidence, trust level, warnings, diagnostic refs, source refs, and suppressed-route reasons into downstream sibling flows.

It does not pass a copy-ready command, final handoff answer, production implementation plan, source mutation request, or account/session state.

The later screen builder should treat this page as the main resolved orientation batch: establish source-health, counts, grouped rows, and desktop selected-preview placement before layering inline selected preview behavior for smaller breakpoints.

## Open Risks

- If warning badges are too subtle, the branch may optimize speed at the cost of source trust.
- If context groups are too prominent, inactive/promoted boundaries may distract from active-path selection.
- If suppressed-route reasons are too terse, users may not understand why a visible row cannot continue normally.
- If selected preview appears too detailed, the page may absorb selected-path verification and blur sibling-flow boundaries.

---

# Page Intermediate: Selected Row Preview Page Spec

Source file: `design/afps-tracker/ui-interview-quick-scan-overview/selected-row-preview.md`

# Selected Row Preview Page Spec

## Scope

The Selected Row Preview is the compact confirmation state that appears after an operator selects a product path row in the Quick-Scan Overview branch. It confirms what was selected, preserves trust and warning context, and explains whether `Continue to verify path` is enabled or disabled.

This surface must not become selected-path verification. It may show label, status, stage, trust level, warning count, diagnostic count, source-confidence summary, and the enabled or disabled reason for continuing. It must not expose copy-next-command behavior, full evidence/provenance detail, repair instructions, write-back controls, command execution, final handoff/export, or implementation sequencing.

## Source Evidence

- Confirmed brief: `design/afps-tracker/_working/ui-interview-quick-scan-overview-brief.md`
- Whole-branch mockup reference: `design/afps-tracker/_working/ui-mockup-quick-scan-overview.html`
- Parent UX variation: `design/afps-tracker/ux-variations-uf-orient-portfolio.md`
- Parent flow branch: `uf-orient-portfolio`
- Existing intermediate references:
  - `design/afps-tracker/ui-interview-quick-scan-overview/loading-scan.md`
  - `design/afps-tracker/ui-interview-quick-scan-overview/portfolio-overview.md`

## User Goal And Success Condition

The operator should be able to confirm that the intended row is selected and understand the next safe route without opening a full detail page.

Success conditions:

- Selected path identity is unmistakable.
- Current status, pipeline stage, and source trust are visible.
- Warning and diagnostic counts remain visible after selection.
- `Continue to verify path` is enabled only for active or warning-level route-safe paths.
- Disabled or suppressed continuation explains the reason in plain language.
- Secondary links route to sibling flows without expanding this preview into full verification.

## Layout Anatomy

### Desktop And Wide Desktop

On desktop, the preview appears in the right column of the Portfolio Overview workspace.

Placement and structure:

1. Right-side panel, approximately 340-380px wide.
2. Panel top aligns with the grouped path list top, below any portfolio-level warning or blocking banner.
3. Selected identity block at the top.
4. Compact status and trust summary below the identity block.
5. Warning/diagnostic summary below trust facts.
6. Primary action block with enabled or disabled reason.
7. Secondary links at the bottom.

Desktop spacing:

- Panel padding: 16-20px.
- Section gaps: 14-18px.
- Badge rows wrap within the panel instead of overflowing.
- Primary action width: full panel width.
- The panel may become sticky below the header only when it does not overlap source-health, count summary, or warning banners.

When no row is selected, the panel remains present as an empty-selection prompt so the right column does not jump.

### Tablet

At widths below approximately 1040px:

- The preview becomes an inline expansion directly below the selected row.
- It spans the row list width.
- It keeps the same content order as desktop.
- It should visually connect to the selected row with a restrained border, inset, or selected-state continuation.
- It must not push source-health or count summary below the fold when a user selects a row.

### Mobile

At widths below approximately 700px:

- The preview appears immediately after the selected row as a compact vertical expansion.
- Identity, status, and trust facts stack in single-column order.
- Primary action remains at least 44px tall.
- Secondary links wrap into stacked text or icon+text buttons.
- Long path IDs and scope paths wrap with preserved readability; do not force horizontal scroll.

## Component Inventory

### Empty Selection Panel

Shown before a row is selected.

Content:

- Heading: `Select a path`
- Helper: `Choose an active or warning-level path to preview the next verification route.`
- Optional source reminder: `Warnings and source confidence will carry forward.`

The empty panel may include a disabled primary action to reserve space:

- Label: `Continue to verify path`
- Disabled reason: `Select an active path to continue.`

Do not show fake selected path data.

### Selected Identity Block

Content:

- Path label.
- Path ID.
- Scope path, when available.
- Selected-state label: `Selected path`.
- Optional last touched value when already present in the row data.

Rules:

- Path label is the most prominent text in the panel.
- Path ID and scope path are secondary and wrap safely.
- If label is missing but path ID exists, use the ID as the primary visible identifier and show `Label unavailable` as a warning-level metadata fact.

### Compact Status Summary

Fields:

- Status or boundary kind.
- Pipeline stage.
- Next safe branch or next skill, only as routing context.
- Trust level.
- Parser confidence.
- Source confidence.

Display:

- Use compact labelled rows or small status blocks.
- Preserve exact trust semantics from the row; do not upgrade partial, inferred, or warning-level source to clean language.
- `Next safe branch` is descriptive context, not a copy-ready command.

### Warning And Diagnostic Summary

Content:

- Warning count.
- Diagnostic count.
- Highest severity label.
- Affected source summary when compact enough.

State labels:

- `Clean`
- `{n} warnings`
- `Partial source`
- `Blocked`
- `Unresolved`
- `Contradicted`
- `Unreadable source`
- `Malformed source`

Rules:

- Warning and blocked facts must remain visible without hover.
- Use color, icon/shape, and text together.
- If there are warnings but continuation is still allowed, state that warnings will carry into verification.
- If a diagnostic blocks continuation, show the disabled reason before secondary links.

### Primary Action Block

Primary action:

- `Continue to verify path`

Enabled only when:

- A path is selected.
- The path is active or warning-level.
- No blocking diagnostic affects selected-path verification.
- Required source support is readable.
- The selected path is not promoted, inactive, archived, deferred, revisit-candidate, unsupported, unresolved, contradicted, malformed, unreadable, or out of scope.

Enabled helper copy:

- Clean active path: `Verification will open with source confidence and path context preserved.`
- Warning-level active path: `Warnings will carry into verification.`

Disabled reason examples:

- `Select an active path to continue.`
- `This path has blocking diagnostics. Review them before verification.`
- `Normal active routing is suppressed for promoted paths.`
- `This inactive path can be explained, but not verified as active work.`
- `Required selected-path source support is unreadable.`
- `This path is unresolved, so verification would not be source-backed.`
- `This path is out of scope for AFPS Tracker.`

The disabled reason is visible as text near the disabled action and exposed programmatically.

### Secondary Links

Links are contextual and may be hidden when no relevant refs exist.

#### Inspect Source

Label:

- `Inspect source`

Behavior:

- Routes to source/provenance inspection for the selected row.
- Carries selected path ID, source refs, trust level, parser confidence, source confidence, warnings, and diagnostic refs.

Disabled reason:

- `Source refs are unavailable for this selection.`

#### Review Warnings

Label:

- `Review warnings`

Behavior:

- Routes to warning or diagnostics inspection scoped to the selected row.
- Enabled when warning IDs or diagnostic refs exist.

Disabled reason:

- `No warning refs are available for this selection.`

#### Explain Boundary

Label:

- `Explain boundary`

Behavior:

- Routes promoted, inactive, archived, deferred, revisit-candidate, unsupported, unresolved, or out-of-scope selections to the boundary explanation sibling flow.
- Carries boundary kind, suppression reason, source refs, trust level, and warnings.

Visibility:

- Show for boundary/context rows.
- Hide or disable for clean active selections.

#### Review Diagnostics

Label:

- `Review diagnostics`

Behavior:

- Routes blocked, malformed, unreadable, unresolved, or contradicted selections to diagnostics recovery.
- Carries diagnostic refs and affected source paths.

Visibility:

- Show when diagnostic refs exist or continuation is blocked by a diagnostic condition.

## Control Inventory

### Primary Button: Continue To Verify Path

Label:

- `Continue to verify path`

Behavior:

- Routes to `uf-verify-selected-path`.
- Passes selected path ID, label, scope path, status, stage, trust level, parser confidence, source confidence, warning IDs, diagnostic refs, source refs, and route-safety state.

Disabled behavior:

- Remains focusable only if the design system uses focusable disabled explanatory controls; otherwise place the visible disabled reason immediately after the disabled button.
- Never routes when continuation is blocked.

Screen reader names:

- `Continue to verify {path_label} path`
- `Continue unavailable for {path_label}: {disabled_reason}`

### Secondary Link Buttons

Labels:

- `Inspect source`
- `Review warnings`
- `Explain boundary`
- `Review diagnostics`

Behavior:

- Route to sibling flows only.
- Preserve selection context.
- Do not mutate source files or execute commands.

### Close Or Collapse Control

Desktop:

- No close button is required. Selecting a different row replaces the preview.

Tablet/mobile:

- A collapse control may be used when inline expansion would make long lists hard to scan.

Label:

- `Collapse preview`

Rules:

- Collapsing preview does not clear selected row state unless the user explicitly selects another row.
- Expanded/collapsed state must be programmatically exposed.

## Copy Requirements

Empty selection:

- Heading: `Select a path`
- Helper: `Choose an active or warning-level path to preview the next verification route.`

Selected path:

- Eyebrow: `Selected path`
- Primary action: `Continue to verify path`
- Clean helper: `Ready for selected-path verification.`
- Warning helper: `Warnings will carry into verification.`
- Blocked helper: `Verification is blocked until this source issue is reviewed.`
- Boundary helper: `Normal active routing is suppressed for this path.`

Avoid:

- `Recommended next command`
- Copyable command text
- `Run`
- `Fix`
- `Update source`
- `Export`
- `Share`
- `Resolve automatically`
- Any phrase implying source write-back, command execution, or final handoff readiness.

## Interaction States

### No Selection

- Empty Selection Panel is visible.
- Primary action is disabled or hidden.
- Helper text tells the user to choose an active or warning-level row.
- Secondary links are hidden or disabled.

### Clean Active Selection

- Identity block shows selected path label and ID.
- Status summary reads active/source-backed.
- Warning summary shows `Clean` or `0 warnings` only when source evidence explicitly supports it.
- Primary action is enabled.
- `Inspect source` may be available.
- `Review warnings`, `Explain boundary`, and `Review diagnostics` are hidden or disabled unless refs exist.

### Warning-Level Active Selection

- Warning badge and count are visible.
- Primary action may remain enabled if no blocking diagnostic affects verification.
- Helper text says warnings will carry into verification.
- `Review warnings` is enabled.
- Selection highlight must not look clean.

### Partial Or Inferred Source Selection

- Source confidence is labelled as partial or inferred.
- Actions depending on missing source are disabled with visible reasons.
- Primary action is enabled only if selected-path verification can preserve uncertainty without false claims.
- `Inspect source` or `Review warnings` is available when refs exist.

### Promoted Or Inactive Boundary Selection

- Boundary badge is visible.
- Primary action is disabled.
- Disabled reason explains normal active routing suppression.
- `Explain boundary` is the main available secondary route.
- The preview must not present the path as active next work.

### Unresolved Selection

- `Unresolved` badge is visible.
- Primary action is disabled.
- Diagnostic or source review route is available when refs exist.
- The preview must not invent label, stage, or next-skill facts missing from source.

### Blocking Diagnostic Selection

- Blocked status is prominent.
- Primary action is disabled.
- Disabled reason names the blocking category.
- `Review diagnostics` is enabled.
- Other readable facts remain visible.

### Selection Change

- Selecting another row updates panel content without resetting source-health or row-list scroll position.
- The previous row loses selected state.
- Focus should move predictably to the preview heading or remain on the row control depending on interaction pattern; keyboard users must not lose context.

### Loading

- This preview should not show selected current-state facts while the current scan is unresolved.
- If retained prior selection is shown during Loading / Scan, it must be labelled `Prior selection` and all current actions remain disabled.

### Error

If preview rendering fails while row data remains visible:

- Show `The selected path preview could not be displayed.`
- Keep the selected row highlighted only if route-safety facts are still known.
- Disable `Continue to verify path`.
- Preserve links to source health or diagnostics when refs exist.

### Offline

Offline status does not block this repo-local preview by itself. If shown, label separately:

- `Network is offline. Local selection context remains available.`

## Visual And Spatial Rules

- Keep the preview subordinate to the Portfolio Overview; it confirms selection but should not dominate the page.
- Cards and panels use 8px radius or less.
- Use neutral operational surfaces with restrained status accents.
- Warning, blocked, boundary, and unresolved states require text labels plus visual treatment.
- The selected path label should be prominent but not hero-scale.
- Long IDs, paths, and disabled reasons wrap cleanly.
- The primary action block should be stable in height so changing warning counts does not cause major layout shift.
- Empty and selected states should occupy similar panel width to avoid desktop grid movement.
- Inline mobile expansion should not look like a modal or separate page.
- Do not use decorative imagery, gradients, large illustrations, or marketing-style panels.

## Accessibility Requirements

- The preview region has an accessible name such as `Selected path preview`.
- Empty and selected states announce their heading.
- The selected row in the list exposes selected state with `aria-selected` or equivalent.
- The preview heading references the selected path label.
- Primary action disabled reasons are programmatically associated with the button.
- Warning and blocked summaries include severity and count in accessible text.
- Secondary links have destination-specific labels, not repeated generic `View` text.
- Keyboard order:
  1. Selected row control in the path list
  2. Preview heading
  3. Status and trust summary
  4. Warning or diagnostic summary
  5. `Continue to verify path`
  6. Disabled reason, if present
  7. Secondary links
  8. Collapse control on tablet/mobile, if present
- Touch targets are at least 44px high on touch layouts.
- Reduced motion disables animated panel transitions and uses immediate state replacement.
- Color-blind safe patterns are required for warning, blocked, promoted, unresolved, and selected states.
- Screen reader labels must distinguish active verification from boundary explanation and diagnostics review.

## Data Requirements

Fields this preview may consume:

- Selected path ID.
- Path label.
- Scope path.
- Status.
- Boundary kind.
- Pipeline stage.
- Next safe branch.
- Next skill.
- Trust level.
- Parser confidence.
- Source confidence.
- Warning IDs and warning count.
- Diagnostic refs and diagnostic count.
- Source refs.
- Suppression reason.
- Last touched.
- Route-safety classification.

Fields this preview must not require:

- Full evidence/provenance body.
- Copyable next command.
- Handoff/export metadata.
- Account or collaboration data.
- Remote sync state.
- Production persistence status.
- Source mutation capability.
- Repair command content.

## Transition Rules

- From Portfolio Overview with no selection: show Empty Selection Panel.
- Selecting a clean active row: update selected highlight, show clean active preview, enable `Continue to verify path`.
- Selecting a warning-level active row: update selected highlight, show warning summary, enable continuation only if no blocking diagnostic affects verification.
- Selecting promoted, inactive, archived, deferred, revisit-candidate, unsupported, or out-of-scope context: show boundary preview and suppress normal continuation.
- Selecting unresolved, contradicted, malformed, unreadable, or blocked context: show diagnostic preview and suppress normal continuation.
- Activating `Continue to verify path`: route to selected-path verification with trust and warning context preserved.
- Activating `Inspect source`: route to source/provenance inspection.
- Activating `Review warnings` or `Review diagnostics`: route to diagnostics or warning inspection.
- Activating `Explain boundary`: route to inactive/promoted boundary explanation.

## Downstream Handoff Constraints

The Selected Row Preview may pass selection identity, route-safety classification, trust level, parser confidence, source confidence, warnings, diagnostic refs, source refs, and disabled/suppression reasons to sibling flows.

It does not pass a copy-ready command, final answer, export payload, source mutation request, repair instruction, production implementation plan, account state, or collaboration state.

The later screen builder should treat this state as a layer on top of the Portfolio Overview: desktop right-panel content first, then tablet/mobile inline expansion behavior.

## Open Risks

- If the preview shows too much detail, it may absorb selected-path verification and weaken sibling-flow boundaries.
- If disabled reasons are too terse, users may not understand why a visible row cannot continue.
- If warning-level active selections look visually clean, source-trust safety regresses.
- If inline mobile expansion is too tall, row scanning may become slower than the Quick-Scan thesis supports.

---

# Page Intermediate: Empty / No-AFPS State Page Spec

Source file: `design/afps-tracker/ui-interview-quick-scan-overview/empty-no-afps-state.md`

# Empty / No-AFPS State Page Spec

## Scope

The Empty / No-AFPS State appears when the repo-local scan completes and AFPS Tracker cannot find source-backed AFPS product paths for the current repository scope. Its job is to tell the operator exactly what source was checked, preserve diagnostic visibility, and avoid inventing active-route guidance.

This page may show repository identity, checked source locations, scan freshness, no-path result, source-health facts, missing-source diagnostics, and links into diagnostics or source/provenance sibling flows. It must not show a normal zero-count portfolio overview, fabricate active paths, recommend a next command, expose write-back or repair controls, or imply that AFPS Tracker can continue to selected-path verification without source-backed path evidence.

## Source Evidence

- Confirmed brief: `design/afps-tracker/_working/ui-interview-quick-scan-overview-brief.md`
- Whole-branch mockup reference: `design/afps-tracker/_working/ui-mockup-quick-scan-overview.html`
- Parent UX variation: `design/afps-tracker/ux-variations-uf-orient-portfolio.md`
- Parent flow branch: `uf-orient-portfolio`
- Existing intermediate references:
  - `design/afps-tracker/ui-interview-quick-scan-overview/loading-scan.md`
  - `design/afps-tracker/ui-interview-quick-scan-overview/portfolio-overview.md`
  - `design/afps-tracker/ui-interview-quick-scan-overview/selected-row-preview.md`

## User Goal And Success Condition

The operator should understand that the tracker performed a local scan, found no AFPS product paths, and cannot offer a normal active-route path until source artifacts exist or diagnostics are resolved.

Success conditions:

- Repository identity and scan freshness are visible.
- The page states that no AFPS product paths were found without implying a system failure when the scan was valid.
- Checked source locations are named so the result is auditable.
- Missing, unreadable, malformed, or unsupported source diagnostics remain visible.
- Primary continuation into selected-path verification is absent or disabled with an explicit reason.
- Links into source health or diagnostics preserve source refs and diagnostic refs when available.
- The empty state does not include copyable command guidance, repair instructions, write-back controls, or fabricated next work.

## Layout Anatomy

### Desktop And Wide Desktop

Use the same shallow shell as Loading / Scan and Portfolio Overview so the empty result feels like a scan outcome, not a separate marketing-style empty dashboard.

Structure:

1. Header strip at the top, full width, 64-76px tall.
2. Main content constrained to approximately 960-1120px, centered inside the same page padding system as the overview.
3. Source-health strip directly below the header, showing scan completion and no-path source status.
4. Empty result panel below source health.
5. Checked source list and diagnostic summary below the result panel.
6. Secondary actions row below diagnostics.

Desktop spacing:

- Main content horizontal padding: 40px on wide desktop, 24px on standard desktop.
- Major vertical gaps: 16-22px.
- Empty result panel padding: 24-28px.
- Source list and diagnostic summary may use a two-column layout when both have enough content.
- Keep the page vertically compact enough that source-health, result message, and primary disabled reason are visible above the fold on common laptop screens.

Do not reserve the right-side selected preview column in this state. There is no selected path.

### Tablet

At widths below approximately 1040px:

- Keep source-health, empty result, checked source list, diagnostics, and secondary actions in one column.
- Source-list and diagnostics sections stack.
- Secondary actions wrap to multiple rows if needed.
- Keep disabled primary-route reason adjacent to the empty result message.

### Mobile

At widths below approximately 700px:

- Header stacks product title, repository label, and scan freshness.
- Source-health strip becomes stacked status blocks.
- Empty result panel becomes a compact vertical section with no decorative illustration requirement.
- Checked source paths wrap naturally and may use monospace styling for path fragments.
- Secondary actions are full-width or stacked with 44px minimum touch targets.
- Long diagnostic refs wrap without horizontal scrolling.

## Component Inventory

### Header

Content:

- Product title: `AFPS Tracker`
- Repository label: `Repository: {repo_path_or_label}`
- Scan freshness: `Local scan complete {relative_time}` or `Local scan complete`

Rules:

- Keep language repo-local.
- Avoid `sync`, `upload`, `connected`, or remote-service framing.
- Do not show a selected path label.

### Source-Health Strip

Purpose: make the empty result auditable before the page explains the absence of paths.

Cells:

- Source health: clean empty, warning, partial, or blocked.
- Parser confidence: high, medium, low, unknown.
- Source confidence: source-backed empty result, partial, missing, unreadable, malformed, unsupported.
- Checked refs: count and unresolved count.
- Diagnostic issues: warning and blocking counts.

State rules:

- Clean empty result should read as a valid scan result, not as success for active work.
- Missing or partial source must be labelled as `Partial source` or `Missing source`, not clean.
- Blocked source must route to Blocking Diagnostic Summary when no trustworthy empty result can be produced.
- Use color, label text, and icon/shape variation together; do not rely on color alone.

### Empty Result Panel

Content:

- Heading: `No AFPS product paths found`
- Helper: `AFPS Tracker scanned the local source artifacts for this repository and did not find source-backed product paths.`
- Disabled-route reason: `Selected-path verification is unavailable until an AFPS product path is found.`
- Optional locality note: `This result is based on repo-local files, not a network sync.`

Visual rules:

- The heading is prominent but not hero-scale.
- The panel may use a small neutral icon if the existing design system has one; it must not use a large decorative illustration.
- The disabled-route reason should be close to the primary action area or the place where a primary action would normally appear.

### Checked Source List

Purpose: show what was actually inspected.

Content:

- Checked source path labels, such as `research/.progress.yaml` when present.
- Product-path scoped research or design artifacts when the scanner checked them.
- Flow-tree or alignment refs when they were part of discovery.
- Source status for each item: checked, missing, unreadable, malformed, unsupported, skipped, or not present.

Rules:

- Do not show paths that were not evaluated unless clearly labelled as expected-but-not-found.
- Missing expected files may appear as diagnostic rows, not as active paths.
- If no source refs were produced, show `Source refs unavailable` and route any detail control to disabled state.

### Diagnostic Summary

Purpose: preserve troubleshooting context without turning this page into recovery instructions.

Content:

- Warning count.
- Blocking issue count.
- Highest severity.
- Affected source paths or refs.
- Short diagnostic label.

Diagnostic examples:

- `No active product path refs found.`
- `Product path manifest missing.`
- `Scoped product path directory not found.`
- `Source unreadable.`
- `Source malformed.`
- `Unsupported path state.`

Rules:

- If diagnostics explain why AFPS paths could not be found, show them visibly below the empty message.
- If diagnostics are blocking and prevent trust in the no-path result, this page should hand off to Blocking Diagnostic Summary instead.
- Avoid repair-command text and copyable shell snippets.

### Disabled Primary Route Block

The page may reserve the primary-action location to explain why no normal route is available.

Label:

- `Continue to verify path`

State:

- Disabled or absent.

Disabled reason:

- `No AFPS product path is available to verify.`

Rules:

- If shown, the disabled button must be paired with visible helper text.
- Do not allow selection or continuation from this page.
- Do not use the primary button for diagnostics; diagnostics are secondary actions.

### Secondary Actions

Secondary actions must be clearly subordinate to the empty result and source-health facts.

#### Inspect Source Health

Label:

- `Inspect source health`

Behavior:

- Routes to the source/provenance sibling flow when source refs exist.
- Carries repository label, checked refs, source-health state, parser confidence, source confidence, unresolved refs, warning refs, and diagnostic refs.

Disabled reason:

- `Source health details are unavailable because source refs were not produced.`

#### Review Diagnostics

Label:

- `Review diagnostics`

Behavior:

- Routes to diagnostics recovery or Blocking Diagnostic Summary when diagnostic refs exist.
- Carries affected source paths, highest severity, blocking count, warning count, and diagnostic refs.

Disabled reason:

- `No diagnostic refs are available for this scan.`

#### Return To Scan

Label:

- `Scan again`

Behavior:

- Re-runs or visually restarts the local scan in prototype scope only when the prototype supports this interaction.
- Keeps the page in repo-local language and does not imply a file watcher or background sync.

Disabled reason:

- `Rescan is not available in this prototype.`

Rules:

- `Scan again` is optional for the prototype and must not mutate source files.
- Do not show `Create AFPS path`, `Initialize AFPS`, or command-copy actions in this branch.

## Copy Requirements

Primary copy:

- Heading: `No AFPS product paths found`
- Helper: `AFPS Tracker scanned the local source artifacts for this repository and did not find source-backed product paths.`
- Disabled-route reason: `Selected-path verification is unavailable until an AFPS product path is found.`

Source copy:

- `Checked local sources`
- `Source refs unavailable`
- `This result is based on repo-local files.`

Diagnostic copy:

- `Diagnostics`
- `No diagnostic refs are available for this scan.`
- `Some source files could not be checked. Review diagnostics before trusting the empty result.`

Avoid:

- `Everything is set up`
- `No projects yet`
- `Create your first project`
- `Recommended next command`
- Copyable shell commands
- Repair instructions
- Marketing or onboarding copy
- Language that implies the UI can write source artifacts

## Interaction States

### Clean Empty Result

- Source-health strip shows a completed, source-backed empty result.
- Empty result panel states no AFPS product paths were found.
- Checked source list shows inspected refs.
- Diagnostics section may show zero warning/blocking count only when those counts are source-derived.
- `Continue to verify path` is absent or disabled with `No AFPS product path is available to verify.`

### Missing Source

- Source-health strip reads `Missing source` or `Partial source`.
- Checked source list identifies missing expected refs.
- Diagnostic summary explains which expected source was absent.
- Normal active routing remains unavailable.
- `Review diagnostics` is enabled when diagnostic refs exist.

### Partial Source

- Source-health strip reads `Partial source`.
- Empty result copy clarifies that AFPS paths were not found in the source that could be checked.
- Any unavailable or skipped refs are shown in the checked source list.
- Avoid claiming the repository has no AFPS paths with full certainty.

### Unreadable Or Malformed Source

- Source-health strip shows warning or blocked state depending on severity.
- Diagnostic summary shows affected source paths.
- If a trustworthy empty result cannot be produced, route to Blocking Diagnostic Summary.
- If the page remains visible, the disabled route reason must mention source trust.

### Unsupported Or Out-Of-Scope Repository

- Empty result panel may state that no AFPS product paths were found in the supported repo scope.
- Diagnostic summary identifies unsupported or out-of-scope source facts.
- Secondary action should favor `Inspect source health` or `Review diagnostics`.
- Do not show normal active-route continuation.

### Loading

The Empty / No-AFPS State must not appear while the scan is unresolved. Loading behavior belongs to Loading / Scan.

### Blocking

When blocking source issues prevent AFPS Tracker from safely deciding whether paths exist, route to Blocking Diagnostic Summary instead of presenting this as a valid empty result.

### Error

For UI rendering failure after an empty scan result exists:

- Show `The no-AFPS result could not be displayed.`
- Preserve source-health and diagnostic links if available.
- Do not fabricate path facts.

### Offline

Offline status should not invalidate a repo-local empty result by itself. If shown, label separately:

- `Network is offline. Local source scanning does not require network access.`

## Visual And Spatial Rules

- Keep the state compact, factual, and source-auditable.
- Cards and panels use 8px radius or less.
- Do not use a landing-page hero, oversized illustration, decorative gradient, or onboarding-style empty project prompt.
- The source-health strip remains visually first.
- The empty result panel is the clearest element but should not overpower diagnostics.
- Checked source and diagnostics sections should be visibly connected to the empty result.
- Disabled action styling must not look like a secondary available route.
- Text inside buttons, badges, and status cells must fit at mobile sizes.
- Long source paths wrap with readable line breaks.
- Use neutral surfaces with status accents; avoid a one-hue palette.
- Warning, missing, partial, blocked, and unsupported states use labels plus icons or shape, not color alone.

## Accessibility Requirements

- Main content starts at the source-health strip after the header.
- Source-health strip has an accessible name such as `Portfolio source health`.
- Empty result panel has a heading that announces the no-path result.
- Checked source list is a labelled region, such as `Checked local sources`.
- Diagnostic summary is a labelled region, such as `No-AFPS diagnostics`.
- Disabled primary route, if present, exposes a programmatic disabled state and visible disabled reason.
- Secondary action controls have accessible names that include the action target when useful.
- Warning, missing, partial, blocked, and unsupported states are announced with severity and count when known.
- Focus order:
  1. Header repository context
  2. Source-health strip and source-health link
  3. Empty result panel
  4. Disabled primary route reason, when present
  5. Checked source list
  6. Diagnostic summary
  7. Secondary actions
- Touch targets for buttons and links are at least 44px high on touch layouts.
- Reduced motion disables animated scan-result transitions.
- Color-blind safe patterns are required for clean empty, missing, partial, warning, blocked, and unsupported states.
- Screen readers should not hear fabricated row counts or path labels when no paths exist.

## Data Requirements

Fields this page may consume:

- Repository label or path.
- Scan completion and freshness timestamp.
- Portfolio source-health state.
- Parser confidence.
- Source confidence.
- Checked source refs and statuses.
- Expected source refs when known.
- Unresolved refs count.
- Warning count.
- Blocking issue count.
- Highest diagnostic severity.
- Diagnostic refs.
- Affected source paths.
- Empty result confidence.
- Unsupported or out-of-scope reason.

Fields this page must not require:

- Product path label, ID, or scope path for a fabricated row.
- Selected path ID.
- Full evidence/provenance detail.
- Copyable next command.
- Handoff/export metadata.
- Auth/account data.
- Remote sync state.
- Production persistence status.
- Write-back capability.

## Transition Rules

- From Loading / Scan with a source-backed zero-path result: render Empty / No-AFPS State.
- From Loading / Scan with missing or partial source but enough evidence to explain no found paths: render Empty / No-AFPS State with missing/partial diagnostics visible.
- From Loading / Scan with blocking issue that prevents a trustworthy empty result: route to Blocking Diagnostic Summary.
- From Empty / No-AFPS State to Inspect Source Health: carry checked refs, source-health state, parser confidence, source confidence, unresolved refs, warning refs, and diagnostic refs.
- From Empty / No-AFPS State to Review Diagnostics: carry affected source paths, highest severity, warning count, blocking count, and diagnostic refs.
- From Empty / No-AFPS State to Scan Again: return to Loading / Scan only when the prototype supports a local rescan interaction.
- Do not transition from this page to Selected Row Preview or selected-path verification because no source-backed selected path exists.

---

# Page Intermediate: Blocking Diagnostic Summary Page Spec

Source file: `design/afps-tracker/ui-interview-quick-scan-overview/blocking-diagnostic-summary.md`

# Blocking Diagnostic Summary Page Spec

## Scope

The Blocking Diagnostic Summary appears when source conditions make normal quick-scan routing unsafe. Its job is to interrupt false confidence, name the blocking source facts, preserve any readable portfolio context, and disable or suppress unsafe actions with explicit reasons.

This surface may show repository identity, scan freshness, portfolio-level source health, affected source paths or refs, blocking categories, warning counts, readable rows, suppressed-route reasons, and secondary links into diagnostics, source health, provenance, or boundary explanation sibling flows. It must not expose repair commands, write-back controls, copy-next-command behavior, command execution, final handoff/export, account/collaboration controls, or production implementation sequencing.

## Source Evidence

- Confirmed brief: `design/afps-tracker/_working/ui-interview-quick-scan-overview-brief.md`
- Whole-branch mockup reference: `design/afps-tracker/_working/ui-mockup-quick-scan-overview.html`
- Parent UX variation: `design/afps-tracker/ux-variations-uf-orient-portfolio.md`
- Parent flow branch: `uf-orient-portfolio`
- Existing intermediate references:
  - `design/afps-tracker/ui-interview-quick-scan-overview/loading-scan.md`
  - `design/afps-tracker/ui-interview-quick-scan-overview/portfolio-overview.md`
  - `design/afps-tracker/ui-interview-quick-scan-overview/selected-row-preview.md`
  - `design/afps-tracker/ui-interview-quick-scan-overview/empty-no-afps-state.md`

## User Goal And Success Condition

The operator should understand that AFPS Tracker found blocking source conditions, see which source facts are affected, and still use any readable context without mistaking it for route-safe active work.

Success conditions:

- The blocking condition is visible before any path row or continuation control.
- Affected source files, path refs, or manifest refs are named when available.
- Blocking categories are described in source-trust language, not generic app-error language.
- Readable rows remain visible when they can be safely shown.
- Normal `Continue to verify path` behavior is disabled or suppressed with an explicit reason.
- Secondary actions route to diagnostics, source health, provenance, or boundary explanation without becoming repair instructions.
- The page distinguishes blocking source facts from non-blocking warnings.
- The page does not fabricate active path status, trust level, next skill, or command guidance.

## Layout Anatomy

### Desktop And Wide Desktop

Use the same shallow shell as the Portfolio Overview so the operator can keep orientation while the blocking issue interrupts unsafe continuation.

Structure:

1. Header strip at the top, full width, 64-76px tall.
2. Main content constrained to approximately 1360px, centered on very wide screens.
3. Blocking banner directly below the header and above the source-health strip.
4. Source-health strip below the banner, with blocked state prominent.
5. Two-column diagnostic workspace:
   - Left column: readable grouped rows or source summary.
   - Right column: blocking diagnostic panel and suppressed action explanation.
6. Optional affected-source table below the workspace when multiple refs are involved.
7. Secondary action row below diagnostics.

Desktop spacing:

- Main content horizontal padding: 40px on wide desktop, 24px on standard desktop.
- Major vertical gaps: 16-22px.
- Workspace grid: `minmax(0, 1fr) 360px`, matching the Portfolio Overview selected-preview column.
- Banner padding: 16-20px with dense text and no oversized hero treatment.
- Blocking diagnostic panel padding: 16-20px.
- Rows remain approximately 72-88px tall when readable portfolio rows can be shown.
- Keep the banner, source-health strip, and primary disabled reason visible above the fold on common laptop screens.

The diagnostic panel may become sticky below the header only when it will not overlap the blocking banner or source-health strip. If the blocking explanation is long, prefer normal page scroll over a nested panel scroll.

### Tablet

At widths below approximately 1040px:

- Collapse the diagnostic workspace to one column.
- Keep the blocking banner first, source-health second, then diagnostic panel, then readable rows.
- Move suppressed-route explanation next to the diagnostic panel instead of below every row.
- Readable rows use the same responsive list anatomy as Portfolio Overview.
- Avoid horizontal scrolling for affected-source data; convert source tables to stacked key-value rows when needed.

### Mobile

At widths below approximately 700px:

- Header stacks product title, repository label, and scan freshness.
- Blocking banner becomes a compact alert section with heading, severity, affected count, and short reason.
- Source-health strip becomes stacked status blocks.
- Diagnostic panel and affected-source refs stack vertically.
- Readable rows become compact list items with visible blocked/warning badges.
- Primary disabled action or suppressed-route reason is full width and close to the diagnostic explanation.
- Long source paths, path IDs, and diagnostic refs wrap naturally with readable line breaks; no horizontal table is required.
- Touch targets for secondary actions are at least 44px high.

## Component Inventory

### Header

Content:

- Product title: `AFPS Tracker`
- Repository label: `Repository: {repo_path_or_label}`
- Scan freshness: `Local scan completed with blocking diagnostics` or `Local scan blocked`
- Optional source timestamp when known.

Rules:

- Keep language repo-local.
- Avoid `sync`, `upload`, `connected`, `server error`, or remote-service framing.
- Do not show a selected active path as the primary page title.

### Blocking Banner

Purpose: interrupt the quick path before the user scans rows or acts on selected-path routing.

Default content:

- Heading: `Blocking diagnostics found`
- Summary: `AFPS Tracker found source issues that prevent normal active-path routing. Readable context remains visible, but unsafe actions are disabled.`
- Affected count: `{n} blocking issues`
- Warning count when present: `{m} warnings`
- Highest severity label.
- First affected source path or ref, if compact enough.

Variations:

- Unreadable required source: `Required source could not be read.`
- Malformed source: `A required source artifact is malformed.`
- Contradicted source: `Source artifacts disagree about this path state.`
- Unresolved ref: `A referenced product path could not be resolved.`
- Unsupported scope: `This source state is outside AFPS Tracker's supported scope.`
- Out-of-scope path: `Normal active routing is suppressed for this out-of-scope path.`

Rules:

- The banner uses warning/error text, icon or shape treatment, and color together.
- The banner must not include repair commands or copyable shell text.
- The banner should offer only secondary routes such as `Review diagnostics` or `Inspect source health`.
- The banner does not replace row-level badges; both portfolio-level and row-level blocking facts remain visible.

### Source-Health Strip

Purpose: show the blocked source-trust envelope before row details.

Cells:

- Source health: blocked, partial, contradicted, unreadable, malformed, unsupported.
- Parser confidence: high, medium, low, unknown.
- Source confidence: source-backed partial, missing, contradicted, unresolved, unreadable.
- Checked refs: count and unresolved count.
- Blocking issues: count and warning count.

State rules:

- Blocked state is visually strongest but still uses concise operational styling.
- Partial source must not read as clean.
- Contradicted source must not be summarized as a generic warning if it blocks route safety.
- Unknown confidence should be labelled `Unknown`, not hidden.
- Counts must be source-derived; do not show fabricated zeroes for categories that were not evaluated.

### Blocking Diagnostic Panel

Desktop location: right column.

Tablet/mobile location: directly after the source-health strip.

Content:

- Panel heading: `Why normal routing is blocked`
- Blocking category.
- Affected source path or ref.
- Affected path ID or label when source-backed.
- Highest severity.
- Disabled or suppressed route reason.
- Short note explaining what remains safe to inspect.

Example disabled reasons:

- `Continue is disabled because required source support is unreadable.`
- `Continue is disabled because source artifacts contradict this path's active state.`
- `Continue is disabled because the selected path ref is unresolved.`
- `Normal active routing is suppressed for this promoted or inactive path.`
- `Selected-path verification is unavailable until source trust is restored.`

Rules:

- The panel explains route safety, not implementation repair.
- It may include a compact list of affected refs, but full evidence/provenance detail belongs to sibling flows.
- It must make clear whether readable context is partial, prior, or current.
- It should not use success styling even if some rows remain readable.

### Readable Context Rows

Purpose: preserve orientation when some portfolio data can still be trusted.

Content per row:

- Path label or source-backed fallback ID.
- Path ID.
- Scope path when available.
- Status or boundary badge.
- Pipeline stage when source-backed.
- Trust level.
- Warning count.
- Blocking badge or suppressed-route reason.
- Row-level action: `Review`, `Inspect`, `Explain`, or disabled `Select`.

Rules:

- Rows with blocking diagnostics cannot show normal active continuation.
- Clean-looking rows may remain visible only when their own source facts are readable and not contradicted.
- A row may show `Readable context` when it is visible for orientation but not route-safe.
- Missing label, stage, or next skill facts should be labelled unavailable rather than inferred.
- Warning and blocked badges must remain visible without hover.
- If no rows are trustworthy, replace row area with a source summary instead of fabricated rows.

### Affected Source List

Purpose: make the diagnostic auditable without exposing full provenance detail.

Content:

- Source path or ref.
- Source status: unreadable, malformed, contradicted, unresolved, unsupported, missing, skipped, or blocked.
- Affected path ID when known.
- Blocking category.
- Diagnostic ref.
- Last checked timestamp or scan phase when available.

Rules:

- Use a table on desktop only when it remains readable.
- On tablet/mobile, render each source item as a stacked key-value block.
- Do not include raw file contents.
- Do not include repair commands or write-back controls.
- If refs are unavailable, show `Affected source refs unavailable` and disable source-detail routes with a visible reason.

### Suppressed Primary Route Block

Primary route label:

- `Continue to verify path`

State:

- Disabled or absent when blocking diagnostics affect selected-path verification.

Visible disabled reason:

- `Continue is unavailable while blocking diagnostics affect source trust.`

Rules:

- If the disabled button is shown, it must be paired with visible helper text and programmatic disabled state.
- The disabled control must not look like a secondary available route.
- Do not repurpose the primary action as `Review diagnostics`; diagnostics remain secondary.
- When no selected path exists, explain both missing selection and blocking source state.

### Secondary Actions

Secondary actions are subordinate to the blocking explanation and preserve diagnostic context.

#### Review Diagnostics

Label:

- `Review diagnostics`

Behavior:

- Routes to diagnostics recovery scoped to the blocking issue.
- Carries diagnostic refs, affected source paths, affected path IDs, severity, warning count, blocking count, parser confidence, source confidence, and suppressed-route reasons.

Disabled reason:

- `No diagnostic refs are available for this blocked scan.`

#### Inspect Source Health

Label:

- `Inspect source health`

Behavior:

- Routes to source/provenance inspection for checked refs.
- Carries checked refs, unresolved refs, source-health state, parser confidence, source confidence, diagnostic refs, and warning refs.

Disabled reason:

- `Source refs are unavailable for this blocked scan.`

#### Inspect Readable Source

Label:

- `Inspect readable source`

Behavior:

- Routes to source/provenance inspection only for refs that were read successfully.
- Carries readable source refs, source-backed row IDs, trust level, and warning refs.

Visibility:

- Show only when some source refs are readable.

Disabled reason:

- `No readable source refs are available.`

#### Explain Boundary

Label:

- `Explain boundary`

Behavior:

- Routes promoted, inactive, archived, deferred, revisit-candidate, unsupported, unresolved, or out-of-scope facts to the boundary explanation sibling flow.
- Carries boundary kind, source refs, suppression reason, trust level, warnings, and diagnostic refs.

Visibility:

- Show when the blocking issue is a boundary or scope condition.
- Hide when the issue is only malformed, unreadable, or contradicted source.

## Control Inventory

### Disabled Primary Button: Continue To Verify Path

Label:

- `Continue to verify path`

Disabled behavior:

- Does not route while blocking diagnostics affect selected-path verification.
- Exposes the disabled reason near the button and programmatically.
- Remains focusable only if the design system supports focusable disabled explanatory controls; otherwise place the disabled reason directly after the button.

Screen reader names:

- `Continue to verify path unavailable: blocking diagnostics affect source trust`
- `Continue unavailable for {path_label}: {disabled_reason}`

### Row Review Button

Labels:

- `Review`
- `Review diagnostics`

Behavior:

- Opens row-scoped diagnostic recovery or source review.
- Preserves row ID, source refs, diagnostic refs, warning refs, trust level, and suppression reason.
- Does not select the row for normal verification.

Disabled reason:

- `Review is unavailable because diagnostic refs are missing.`

### Row Inspect Link

Label:

- `Inspect source`

Behavior:

- Opens source/provenance sibling flow for readable source refs.
- Does not expose full evidence in this summary page.
- Does not mutate source.

Disabled reason:

- `Source refs are unavailable for this row.`

### Boundary Explanation Link

Label:

- `Explain boundary`

Behavior:

- Opens boundary explanation for promoted, inactive, archived, deferred, revisit-candidate, unsupported, unresolved, or out-of-scope rows.

Disabled reason:

- `Boundary details are unavailable because source refs are missing.`

### Group Collapse Toggle

Label:

- `Collapse readable context`
- `Expand readable context`

Rules:

- Optional for long readable-row groups.
- Never hides the blocking banner, source-health strip, or diagnostic panel.
- Collapsed state is programmatically exposed.
- Defaults expanded when any row-level blocking issue is present.

## Copy Requirements

Primary copy:

- Heading: `Blocking diagnostics found`
- Summary: `AFPS Tracker found source issues that prevent normal active-path routing. Readable context remains visible, but unsafe actions are disabled.`
- Disabled-route reason: `Continue is unavailable while blocking diagnostics affect source trust.`

Diagnostic copy:

- `Why normal routing is blocked`
- `Affected source`
- `Blocking issue`
- `Readable context`
- `Route suppressed`
- `Source refs unavailable`

Row copy:

- `Readable context only`
- `Selection blocked`
- `Route blocked`
- `Normal active routing suppressed`
- `Warnings remain visible`

Avoid:

- `Recommended next command`
- Copyable shell commands
- `Run`
- `Fix`
- `Repair automatically`
- `Resolve now`
- `Update source`
- `Write back`
- `Export`
- `Share`
- `Everything is safe`
- Any phrase implying command execution, source mutation, final handoff readiness, or full evidence review inside this page.

## Interaction States

### Blocking With Readable Rows

- Blocking banner appears above source-health.
- Source-health strip shows blocked or partial source state.
- Readable rows remain visible with `Readable context only` or row-level suppression labels.
- Normal row selection and `Continue to verify path` are disabled.
- `Review diagnostics`, `Inspect source health`, or `Inspect readable source` are available when refs exist.

### Blocking With No Trustworthy Rows

- Blocking banner appears above source-health.
- Row area is replaced by a source summary or affected-source list.
- No selected preview is shown.
- Primary continuation is absent or disabled with visible reason.
- Secondary action favors `Review diagnostics`.

### Unreadable Required Source

- Source-health strip reads `Unreadable source` or `Blocked`.
- Affected source list names unreadable path or `Affected source refs unavailable`.
- Rows depending on the unreadable source are hidden, disabled, or labelled unavailable.
- Normal active routing remains unavailable.

### Malformed Source

- Source-health strip reads `Malformed source`.
- Diagnostic panel names the malformed source artifact and affected path ref when known.
- Do not parse partial row facts into confident labels unless the data is source-backed outside the malformed artifact.
- `Review diagnostics` is the primary secondary action.

### Contradicted Source

- Source-health strip reads `Contradicted source`.
- Diagnostic panel states that source artifacts disagree about route safety or path state.
- Any affected row shows `Contradicted` and cannot be selected for normal verification.
- Do not choose one source as canonical on this page.

### Unresolved Ref

- Source-health strip shows unresolved ref count.
- Affected source list names the unresolved ref when available.
- Row label falls back to source-backed ID only when that ID exists.
- `Continue to verify path` is disabled because verification would not be source-backed.

### Boundary Or Scope Block

- Blocking banner may read as suppressed active routing rather than malformed source.
- Row shows boundary kind, such as promoted, inactive, archived, deferred, revisit-candidate, unsupported, or out of scope.
- Primary continuation is disabled.
- `Explain boundary` is the main secondary route when boundary details exist.

### Warning-Level But Not Blocking

This page should not appear for warning-only conditions. Warning-only states belong in Portfolio Overview and Selected Row Preview with visible warning badges and enabled continuation when route-safe.

If a warning escalates during the scan:

- Replace warning-only overview with Blocking Diagnostic Summary only when route safety becomes blocked.
- Preserve warning refs alongside blocking refs.

### Loading

Blocking Diagnostic Summary should not appear until the scan knows a blocking condition exists. Early source-access failures during scan may appear as the Loading / Scan early diagnostic banner first.

### Error

If the diagnostic summary itself cannot render while source-health facts exist:

- Show `Blocking diagnostics could not be displayed.`
- Keep source-health strip visible when available.
- Disable `Continue to verify path`.
- Preserve `Inspect source health` when refs exist.

### Offline

Offline network state does not itself create a blocking diagnostic for repo-local AFPS scanning. If shown, label separately:

- `Network is offline. Local diagnostic context remains available.`

## Visual And Spatial Rules

- The page should feel like an operational interruption, not a full error landing page.
- The blocking banner is prominent but compact; avoid hero-scale type.
- Cards and panels use 8px radius or less.
- Use neutral surfaces with distinct status accents for blocked, warning, partial, unresolved, and boundary states.
- Do not rely on red alone; include labels, icons or shape, and severity text.
- The source-health strip remains visually before row context.
- Readable rows must look less actionable than route-safe Portfolio Overview rows.
- Disabled primary action styling must be clearly unavailable and paired with explanatory copy.
- Long source paths and diagnostic refs wrap cleanly.
- Text inside badges and buttons must fit at mobile sizes.
- Avoid decorative images, gradients, large illustrations, or marketing-style empty/error layouts.
- Do not use nested cards for the banner, diagnostic panel, affected source list, or rows.
- Dynamic warning and blocking counts should not cause major layout shifts.

## Accessibility Requirements

- The blocking banner has an alert role or equivalent announcement pattern appropriate to the design system.
- The banner heading is the first meaningful content after the header.
- Source-health strip has an accessible name such as `Portfolio source health`.
- Blocking diagnostic panel has an accessible name such as `Blocking diagnostic summary`.
- Affected source list is a labelled region or table with clear row and column labels.
- Disabled primary route exposes both disabled state and visible disabled reason.
- Row-level blocked, warning, boundary, unresolved, and partial states include severity and count in accessible text.
- Secondary links have destination-specific labels, not repeated generic `View` text.
- Keyboard order:
  1. Header repository context
  2. Blocking banner
  3. `Review diagnostics` or banner secondary action, when present
  4. Source-health strip
  5. Blocking diagnostic panel
  6. Disabled primary route and disabled reason
  7. Readable context rows or source summary
  8. Row-level review/inspect/explain links
  9. Affected source list
  10. Secondary action row
- Focus must not jump to a disabled continuation control when the page appears.
- Touch targets are at least 44px high on touch layouts.
- Reduced motion disables animated alert transitions and uses immediate state replacement.
- Color-blind safe patterns are required for blocked, warning, partial, unresolved, contradicted, and boundary states.
- Screen reader labels must distinguish normal active verification from diagnostic review and boundary explanation.

## Data Requirements

Fields this page may consume:

- Repository label or path.
- Scan completion and freshness timestamp.
- Portfolio source-health state.
- Parser confidence.
- Source confidence.
- Checked source refs and statuses.
- Readable source refs.
- Unreadable, missing, malformed, unsupported, contradicted, unresolved, and skipped refs.
- Warning count.
- Blocking issue count.
- Highest diagnostic severity.
- Diagnostic refs.
- Affected source paths.
- Affected path IDs and labels when source-backed.
- Boundary kind.
- Suppression reason.
- Route-safety classification.
- Trust level for readable rows.
- Pipeline stage for source-backed readable rows.

Fields this page must not require:

- Full evidence/provenance body.
- Copyable next command.
- Handoff/export metadata.
- Auth/account data.
- Collaboration data.
- Remote sync state.
- Production persistence status.
- Source mutation capability.
- Repair command content.
- Final implementation plan.

## Transition Rules

- From Loading / Scan with blocking source issue: render Blocking Diagnostic Summary once the blocking condition is known.
- From Portfolio Overview when portfolio-level blocking issue appears: show Blocking Diagnostic Summary while preserving readable rows when safe.
- From Portfolio Overview when selected row has blocking diagnostic: show row-scoped Blocking Diagnostic Summary or selected preview blocked state according to prototype scope; normal continuation remains disabled.
- From Empty / No-AFPS State when a trustworthy empty result cannot be produced: route to Blocking Diagnostic Summary.
- From Blocking Diagnostic Summary to Review Diagnostics: carry diagnostic refs, affected source paths, affected path IDs, severity, warning count, blocking count, parser confidence, source confidence, and suppression reasons.
- From Blocking Diagnostic Summary to Inspect Source Health: carry checked refs, readable refs, unresolved refs, source-health state, parser confidence, source confidence, diagnostic refs, and warning refs.
- From Blocking Diagnostic Summary to Inspect Readable Source: carry only readable source refs and source-backed row IDs.
- From Blocking Diagnostic Summary to Explain Boundary: carry boundary kind, source refs, suppression reason, trust level, warnings, and diagnostic refs.
- Do not transition from this page to selected-path verification while blocking diagnostics affect route safety.
- Do not transition from this page to copy-next-command, handoff/export, source repair, write-back, or production implementation planning.

## Downstream Handoff Constraints

The Blocking Diagnostic Summary may pass source-health state, route-safety classification, parser confidence, source confidence, warning refs, diagnostic refs, affected source paths, affected path IDs, readable source refs, boundary kind, suppression reason, and disabled-route reasons to sibling flows.

It does not pass a copy-ready command, final answer, export payload, source mutation request, repair instruction, production implementation plan, account state, collaboration state, or full evidence/provenance body.

The later screen builder should treat this as the route-safety interruption for Quick-Scan Overview: banner and source-health first, readable context second, disabled primary continuation with explicit reason, and diagnostics/source/boundary routes as secondary exits only.

Table of Contents

Interview Stage

Rendered Working Packet

Preliminary UI Interview Research: Quick-Scan Overview

Interview Stage

Proposed Canonical Destinations

Source Evidence

Branch Investigation And Decision Record

Prototype-First Boundary

Coverage Checkpoint

UI Interview Brief: Quick-Scan Overview

Confirmed UI Assumptions Manifest

Confirmed Open Decisions

Scope Boundaries

Page Inventory

Loading / Scan

Portfolio Overview

Selected Row Preview

Empty / No-AFPS State

Blocking Diagnostic Summary

Global Shell And Navigation Decisions

Evaluation Criteria

Carried Branch Decision Context

Page Intermediate: Loading / Scan Page Spec

Loading / Scan Page Spec

Scope

Source Evidence

User Goal And Success Condition

Layout Anatomy

Desktop And Wide Desktop

Tablet

Mobile

Component Inventory

Header

Source-Health Skeleton Strip

Count Summary Skeletons

Grouped Row Skeletons

Scan-Status / Prior-State Panel

Early Diagnostic Banner

Control Inventory

Disabled Row Select Placeholders

Secondary Link: Source Health

Secondary Link: Diagnostics

Primary Action Placeholder

Copy Requirements

Interaction States

Default Loading

Slow Loading

Prior State Retained

Early Warning

Early Blocking Issue

Empty Completion Transition

Error

Offline

Visual And Spatial Rules

Accessibility Requirements

Data Requirements

Transition Rules

Downstream Handoff Constraints

Open Risks

Page Intermediate: Portfolio Overview Page Spec

Portfolio Overview Page Spec

Scope

Source Evidence

User Goal And Success Condition

Layout Anatomy

Desktop And Wide Desktop

Tablet

Mobile

Component Inventory

Header

Source-Health Strip

Portfolio Count Summary

Grouped Path List

Product-Path Row

Warning And Diagnostic Badges

Selected Preview Region

Control Inventory

Row Select Button

Explain Button