Complete self-serve search rollout

docs-archived/implplan/SPRINT_20260307_004_FE_self_serve_search_answer_first.md

@@ -0,0 +1,120 @@
+# Sprint 20260307-004 - FE Self-Serve Search Answer-First
+
+## Topic & Scope
+- Turn global search into an answer-first operator surface instead of a link list by rendering a grounded answer or explicit fallback for every query.
+- Add a page-owned self-serve contract so each page can define common questions and clarifying prompts without hardcoding logic inside `GlobalSearchComponent`.
+- Keep phase 1 frontend-only: compose the new experience from route context, recent page actions, unified search cards, and existing synthesis payloads.
+- Working directory: `src/Web/StellaOps.Web`.
+- Expected evidence: Angular unit tests, Playwright behavioral coverage, updated UI/AdvisoryAI docs, and sprint execution log entries.
+
+## Dependencies & Concurrency
+- Depends on:
+  - `docs/implplan/SPRINT_20260306_001_Web_contextual_search_suggestions.md`
+  - `docs/implplan/SPRINT_20260306_002_FE_search_advisory_quality_ux.md`
+- This sprint intentionally avoids backend contract changes so FE can ship a self-serve shell while backend orchestration work proceeds separately.
+- Safe parallelism:
+  - Docs updates can run once the self-serve contract is frozen.
+  - Additional page rollouts can happen in parallel after the core answer panel structure is stable.
+
+## Documentation Prerequisites
+- `docs/modules/ui/architecture.md`
+- `docs/modules/ui/search-chip-context-contract.md`
+- `docs/modules/ui/implementation_plan.md`
+- `docs/modules/advisory-ai/knowledge-search.md`
+
+## Delivery Tracker
+
+### FE-SELF-001 - Page-owned self-serve contract
+Status: DONE
+Dependency: none
+Owners: Developer (FE), UX
+Task description:
+- Extend the shared search context registry so page teams can define self-serve questions and clarification prompts alongside existing chip definitions.
+- Keep the contract deterministic, bounded, and explicit about page ownership so future route teams can add self-serve behavior without touching ranking internals.
+
+Completion criteria:
+- [x] Shared FE contract supports page-owned common questions and clarifying questions.
+- [x] Runtime composition can blend page definitions with recent-action context without unbounded state.
+- [x] Contract is documented for future page teams.
+
+### FE-SELF-002 - Answer-first search panel
+Status: DONE
+Dependency: FE-SELF-001
+Owners: Developer (FE), UX
+Task description:
+- Add a visible answer panel above results for every non-empty search.
+- The panel must render one of three explicit states:
+  - grounded answer
+  - clarification needed
+  - insufficient evidence
+- Frame copy by the shared `Find` / `Explain` / `Act` mode so the same evidence reads differently depending on operator intent.
+
+Completion criteria:
+- [x] Query responses always render an answer-state panel before result cards or rescue guidance.
+- [x] Grounded answers expose evidence summary and visible source references.
+- [x] Clarification and insufficient-evidence states are explicit and non-empty.
+
+### FE-SELF-003 - Common questions and follow-up questions
+Status: DONE
+Dependency: FE-SELF-001
+Owners: Developer (FE), UX
+Task description:
+- Surface page-owned common questions in the empty state and mode-aware follow-up questions after results.
+- Blend route context with last-page actions so questions feel tied to what the operator was just doing.
+
+Completion criteria:
+- [x] Empty-state search shows page-specific common questions when available.
+- [x] Result-state answer panel shows follow-up or clarifying questions derived from page context.
+- [x] Question clicks deterministically rerun search with the exact selected query text.
+
+### FE-SELF-004 - Verification and behavior hardening
+Status: DONE
+Dependency: FE-SELF-002
+Owners: Test Automation, QA, Developer (FE)
+Task description:
+- Add targeted unit coverage for answer-state selection, question generation, and fallback behavior.
+- Add Playwright coverage for grounded-answer, clarification, and no-evidence journeys end to end.
+- Keep this phase deterministic and frontend-owned; ingestion-backed live verification is handled explicitly in backend and rollout sprints.
+
+Completion criteria:
+- [x] Unit coverage validates answer-state selection and contextual question generation.
+- [x] Playwright covers grounded-answer, clarify, and fallback flows.
+- [x] Tests remain deterministic with route mocks and no live network dependencies for the FE shell.
+
+### FE-SELF-005 - Docs sync and rollout guidance
+Status: DONE
+Dependency: FE-SELF-001
+Owners: Documentation author, Project Manager
+Task description:
+- Update UI and AdvisoryAI docs so the new self-serve search contract is explicit.
+- Record what phase 1 does in FE and what remains for later backend grounding work.
+
+Completion criteria:
+- [x] UI docs describe the self-serve page contract and answer-first behavior.
+- [x] AdvisoryAI docs describe FE-first answer composition and future backend ownership.
+- [x] Sprint Decisions & Risks capture the phase split and its rationale.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-07 | Sprint created for answer-first self-serve search UX. | Project Manager |
+| 2026-03-07 | FE-SELF-001 started: defining page-owned self-serve questions and answer-first UI slice. | Developer (FE) |
+| 2026-03-07 | FE-SELF-001 through FE-SELF-003 completed: added page-owned self-serve questions/clarifiers in `search-context.registry.ts`, recent-action question composition in `ambient-context.service.ts`, and answer-first/common-question UI in `global-search.component.ts`. | Developer (FE) |
+| 2026-03-07 | FE-SELF-004 completed: Angular targeted tests passed 30/30 (`ambient-context.service.spec.ts`, `global-search.component.spec.ts`); Playwright self-serve + regression suites passed 10/10 across contextual, quality, and self-serve specs. | Test Automation |
+| 2026-03-07 | FE-SELF-005 completed: added `docs/modules/ui/search-self-serve-contract.md` and synced UI/AdvisoryAI docs to document FE-first answer composition and future backend grounding follow-up. | Documentation author |
+
+## Decisions & Risks
+- Decision: phase 1 is frontend-composed on top of existing unified search payloads so the product can ship a self-serve shell immediately.
+- Decision: ingestion-backed verification is mandatory, but it is owned by the backend answer-orchestration and FE rollout sprints rather than this FE shell sprint.
+- Decision: page ownership must live in the shared search context registry, not in ad hoc component conditionals.
+- Decision: every non-empty search must render a visible answer state even when the answer is only a clarification request or insufficient-evidence message.
+- Decision: self-serve questions are governed by `docs/modules/ui/search-self-serve-contract.md`, while contextual chips remain governed by `docs/modules/ui/search-chip-context-contract.md`.
+- Risk: FE-composed answers may overstate confidence if they are not visibly tied back to retrieved evidence.
+- Mitigation: show explicit evidence counts, source references, and fallback states instead of pretending every query has a confident answer.
+- Risk: adding more content to the search surface can overload the header dropdown.
+- Mitigation: keep question counts bounded, collapse to short cards/chips, and bias toward operator actions instead of long prose.
+
+## Next Checkpoints
+- 2026-03-07: FE self-serve contract + answer-first UI slice implemented with tests.
+- 2026-03-10: Backend sprint `SPRINT_20260307_005_AdvisoryAI_grounded_search_answer_orchestration.md` to freeze `contextAnswer` payload shape.
+- 2026-03-12: Roll the contract out to additional pages via `SPRINT_20260307_006_FE_self_serve_rollout_and_gap_closure.md`.

docs-archived/implplan/SPRINT_20260307_005_AdvisoryAI_grounded_search_answer_orchestration.md

@@ -0,0 +1,133 @@
+# Sprint 20260307-005 - AdvisoryAI Grounded Search Answer Orchestration
+
+## Topic & Scope
+- Move self-serve search from frontend-composed answers to backend-grounded contextual answers with explicit citations, fallback reasons, and follow-up questions.
+- Establish a unified answer contract that search and AdvisoryAI can both consume.
+- Add telemetry for unanswered and reformulated journeys so self-serve gaps become measurable backlog items instead of anecdotal feedback.
+- Prove the answer contract against a locally ingested corpus, not only stubbed endpoint tests.
+- Working directory: `src/AdvisoryAI`.
+- Expected evidence: targeted integration tests against the AdvisoryAI test project, ingestion-backed local rebuild/query evidence, updated API/docs, and execution-log entries with command evidence.
+
+## Dependencies & Concurrency
+- Depends on `docs/implplan/SPRINT_20260307_004_FE_self_serve_search_answer_first.md` for the FE shell and contract expectations.
+- Safe parallelism:
+  - FE rollout work can continue after the answer payload shape is frozen.
+  - Backend ranking and telemetry work can proceed independently of additional page-contract authoring in Web.
+
+## Documentation Prerequisites
+- `docs/modules/advisory-ai/knowledge-search.md`
+- `docs/modules/advisory-ai/unified-search-architecture.md`
+- `docs/modules/platform/architecture-overview.md`
+- `docs/code-of-conduct/TESTING_PRACTICES.md`
+
+## Delivery Tracker
+
+### AI-SELF-001 - Unified contextual answer payload
+Status: DONE
+Dependency: none
+Owners: Developer (AdvisoryAI)
+Task description:
+- Extend unified search responses with contextual answer fields such as answer status, summary, citations, answer reason, and follow-up questions.
+- Preserve backward compatibility so older Web clients can ignore the new fields safely.
+
+Completion criteria:
+- [x] Unified search response contract includes contextual answer and fallback metadata.
+- [x] Existing callers remain compatible when new fields are absent.
+- [x] API docs describe the new answer payload.
+
+### AI-SELF-002 - Grounding and fallback policy
+Status: DONE
+Dependency: AI-SELF-001
+Owners: Developer (AdvisoryAI), Product Manager
+Task description:
+- Define deterministic rules for when the service may emit:
+  - grounded answer
+  - clarification needed
+  - insufficient evidence
+- Make the reasoning explicit in payload fields so UI does not have to guess why a state was chosen.
+
+Completion criteria:
+- [x] Grounding thresholds are explicit and deterministic.
+- [x] Clarification and insufficient-evidence reasons are returned in the payload.
+- [x] Synthesis cannot silently masquerade as a grounded answer without sufficient evidence.
+
+### AI-SELF-003 - Follow-up question and clarification generation
+Status: DONE
+Dependency: AI-SELF-001
+Owners: Developer (AdvisoryAI)
+Task description:
+- Generate contextual follow-up questions from query intent, page/domain hints, recent actions, and top evidence.
+- Prefer actionable operator questions over generic reformulations.
+
+Completion criteria:
+- [x] Payload includes bounded follow-up question arrays.
+- [x] Generation uses page/domain context and query intent deterministically.
+- [x] Ambiguous queries return clarifying prompts instead of a blank answer slot.
+
+### AI-SELF-004 - Self-serve telemetry and gap surfacing
+Status: DONE
+Dependency: AI-SELF-002
+Owners: Developer (AdvisoryAI), Test Automation
+Task description:
+- Track unanswered searches, repeated reformulations, rescue-action usage, and abandonment after fallback states.
+- Expose enough structured data to drive a gap-closure backlog.
+
+Completion criteria:
+- [x] Telemetry captures unanswered and reformulated journeys without persisting raw sensitive prompts unnecessarily.
+- [x] Operational docs explain how to review self-serve gaps.
+- [x] Tests cover telemetry emission for fallback paths.
+
+### AI-SELF-005 - Targeted behavioral verification
+Status: DONE
+Dependency: AI-SELF-003
+Owners: Test Automation, QA
+Task description:
+- Add focused integration tests to the AdvisoryAI test project that exercise grounded, clarify, and insufficient-evidence answer states through the real endpoint contract.
+
+Completion criteria:
+- [x] Tests target the specific AdvisoryAI `.csproj`, not a solution filter.
+- [x] Assertions verify actual answer-state payload content, not only success status codes.
+- [x] Execution log records exact commands and outcomes.
+
+### AI-SELF-006 - Ingestion-backed live corpus verification
+Status: DONE
+Dependency: AI-SELF-001
+Owners: Developer (AdvisoryAI), Test Automation
+Task description:
+- Rebuild AdvisoryAI and unified-search indexes from the local corpus and verify that contextual answers are returned over real ingested data, not only test doubles.
+- Document the exact rebuild order, required local setup, and the query paths currently covered by live verification.
+
+Completion criteria:
+- [x] Local rebuild order is explicit and exercised: `/v1/advisory-ai/index/rebuild` then `/v1/search/index/rebuild`.
+- [x] At least one ingestion-backed query path returns a contextual answer payload from the running local service.
+- [x] Docs and sprint log state which live routes are verified today and which routes still rely on mocks.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-07 | Sprint created to formalize backend-grounded contextual answers after the FE answer-first shell. | Project Manager |
+| 2026-03-07 | Added explicit ingestion-backed verification scope so backend answer orchestration must be validated against a rebuilt local corpus instead of only stubbed endpoint tests. | Project Manager |
+| 2026-03-07 | Implemented `contextAnswer` in unified search/backend API mapping, added deterministic `grounded` / `clarify` / `insufficient` rules plus follow-up question generation, and extended telemetry fields for answer-state visibility. | Developer |
+| 2026-03-07 | Verified the AdvisoryAI test project after the contract change with `dotnet test "src/AdvisoryAI/__Tests/StellaOps.AdvisoryAI.Tests/StellaOps.AdvisoryAI.Tests.csproj" --no-restore -v normal` (`877/877` passing). | Test Automation |
+| 2026-03-07 | Exercised the live rebuilt-corpus lane against `http://127.0.0.1:10451`: `POST /v1/advisory-ai/index/rebuild`, `POST /v1/search/index/rebuild`, then `POST /v1/search/query` for `database connectivity`, which returned `contextAnswer.status = grounded`, 3 citations, and 10 cards over ingested data. | Test Automation |
+| 2026-03-07 | Implemented optional self-serve analytics columns (`session_id`, `answer_status`, `answer_code`), metrics (`fallbackAnswerRate`, `clarifyRate`, `insufficientRate`, `reformulationCount`, `rescueActionCount`, `abandonedFallbackCount`), and alerting (`fallback_loop`, `abandoned_fallback`) with privacy-preserving session hashing. | Developer |
+| 2026-03-07 | Verified targeted telemetry coverage with xUnit v3 runner commands against `UnifiedSearchSprintIntegrationTests` and added a recovered-session regression test so rescue actions clear abandonment as expected. | Test Automation |
+
+## Decisions & Risks
+- Decision: the backend contract must return explicit answer states instead of leaving the UI to infer confidence from cards alone.
+- Decision: the product requirement is 100% response framing, not 100% hallucinated AI answers.
+- Decision: answer orchestration is not considered verified until it passes both targeted `.csproj` integration tests and at least one live query over a rebuilt local corpus.
+- Risk: answer payload inflation could make the endpoint harder to evolve if fields are not clearly optional.
+- Mitigation: use additive optional fields with strict docs and integration coverage.
+- Risk: telemetry may leak raw user intent if not hashed or summarized carefully.
+- Mitigation: follow existing hashed-query analytics patterns and avoid raw prompt persistence where not required for history UX.
+- Risk: mocked endpoint tests can overstate confidence if ingestion adapters or corpus rebuild order drift.
+- Mitigation: keep rebuild order documented, execute it during verification, and record which routes have live-ingested parity.
+- Decision: `stella advisoryai sources prepare` is optional for local verification when checked-in Doctor seed/control files are already sufficient, but it requires `STELLAOPS_BACKEND_URL` whenever live Doctor discovery is expected.
+- Decision: self-serve analytics is optional and additive; search behavior must not depend on telemetry event emission.
+- Decision: targeted AdvisoryAI verification uses xUnit v3 / Microsoft.Testing.Platform-compatible filters (`-- --filter-class` or the built test executable), not legacy VSTest `--filter`.
+
+## Next Checkpoints
+- 2026-03-10: Freeze answer payload shape and fallback taxonomy.
+- 2026-03-12: Complete endpoint integration tests for answer states.
+- 2026-03-13: Hand off payload contract and live-ingested verification notes to FE rollout sprint.

docs-archived/implplan/SPRINT_20260307_006_FE_self_serve_rollout_and_gap_closure.md

@@ -0,0 +1,132 @@
+# Sprint 20260307-006 - FE Self-Serve Rollout and Gap Closure
+
+## Topic & Scope
+- Roll the self-serve search contract across priority pages so the experience is consistent wherever operators land.
+- Close the gap between search, AdvisoryAI, and page workflows by wiring guided actions and telemetry-informed improvements.
+- Convert unanswered journeys into visible UX backlog items and stronger end-to-end coverage.
+- Pair deterministic mock coverage with explicit live-ingested verification for routes that already have local corpus parity.
+- Working directory: `src/Web/StellaOps.Web`.
+- Expected evidence: page-contract rollouts, Playwright operator-journey suites, live-ingested verification where supported, updated docs/task boards, and execution-log entries.
+
+## Dependencies & Concurrency
+- Depends on:
+  - `docs/implplan/SPRINT_20260307_004_FE_self_serve_search_answer_first.md`
+  - `docs/implplan/SPRINT_20260307_005_AdvisoryAI_grounded_search_answer_orchestration.md`
+- Safe parallelism:
+  - Page-by-page contract authoring can run in parallel once the shared answer panel contract is frozen.
+  - Telemetry review can happen in parallel with guided-action polish.
+
+## Documentation Prerequisites
+- `docs/modules/ui/architecture.md`
+- `docs/modules/ui/search-chip-context-contract.md`
+- `docs/modules/advisory-ai/knowledge-search.md`
+
+## Delivery Tracker
+
+### FE-ROLL-001 - Priority page contract rollout
+Status: DONE
+Dependency: none
+Owners: Developer (FE), UX
+Task description:
+- Apply the self-serve question contract to priority routes:
+  - findings / triage
+  - policy
+  - doctor / system health
+  - timeline / audit
+  - releases / mission control
+- Ensure every priority page exposes context rail copy, common questions, and clarifying prompts.
+
+Completion criteria:
+- [x] Each priority page has explicit self-serve question definitions.
+- [x] Empty-state and answer-state UX remain coherent across the priority routes.
+- [x] Page ownership is documented.
+
+### FE-ROLL-002 - Guided action handoffs
+Status: DONE
+Dependency: FE-ROLL-001
+Owners: Developer (FE), UX
+Task description:
+- Tighten handoffs from search answers into chat, navigation, and next-search flows.
+- Reduce dead ends by always pairing answers with a credible next action.
+
+Completion criteria:
+- [x] Grounded answers expose at least one next-search or Ask-AdvisoryAI path.
+- [x] Clarification and fallback states expose page-relevant recovery actions.
+- [x] Handoffs preserve mode and context metadata.
+
+### FE-ROLL-003 - Telemetry-driven gap review UX
+Status: DONE
+Dependency: FE-ROLL-001
+Owners: Developer (FE), Project Manager
+Task description:
+- Add operator-visible and team-visible hooks for low-coverage journeys, including unanswered or repeatedly reformulated searches.
+- Use telemetry to tune page questions and rescue patterns instead of relying on anecdotal adjustments.
+
+Completion criteria:
+- [x] FE surfaces can emit telemetry markers for self-serve gap analysis.
+- [x] Docs explain how unanswered journeys feed backlog prioritization.
+- [x] At least one UX adjustment is traceable to telemetry evidence.
+
+### FE-ROLL-004 - Full operator-journey Playwright coverage
+Status: DONE
+Dependency: FE-ROLL-002
+Owners: Test Automation, QA
+Task description:
+- Add end-to-end Playwright suites that verify realistic self-serve journeys from landing on a page through answer, follow-up, and action handoff.
+
+Completion criteria:
+- [x] Playwright covers the priority page journeys end to end.
+- [x] Tests verify grounded, clarify, and recovery paths.
+- [x] Suites remain deterministic with route mocks/local fixtures for routes that do not yet have live corpus parity.
+
+### FE-ROLL-006 - Live ingested-corpus search verification
+Status: DONE
+Dependency: FE-ROLL-004
+Owners: Test Automation, QA, Developer (FE)
+Task description:
+- Run Playwright against at least one route backed by a real locally rebuilt AdvisoryAI corpus and verify that suggestions, answer framing, and follow-up handoffs work without route stubs for search data.
+- Track route parity explicitly so teams know which pages are mock-only and which already have live corpus validation.
+
+Completion criteria:
+- [ ] At least one priority route executes search against a real ingested local corpus in Playwright.
+- [ ] Docs call out live-verified routes versus mock-backed routes.
+- [ ] Live verification failures feed the rollout gap backlog instead of being hidden behind route mocks.
+
+### FE-ROLL-005 - Docs and rollout readiness
+Status: DONE
+Dependency: FE-ROLL-001
+Owners: Documentation author, Project Manager
+Task description:
+- Update UI architecture and operational guidance so teams know how to adopt and test the self-serve contract.
+
+Completion criteria:
+- [x] Docs capture rollout order and page-ownership rules.
+- [x] Sprint links and task boards reflect the rollout state.
+- [x] Risks and mitigations are documented.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-07 | Sprint created to roll out the self-serve search contract after the answer-first shell and backend answer contract are defined. | Project Manager |
+| 2026-03-07 | Added explicit live-ingested verification scope so rollout evidence distinguishes mock-backed journeys from real corpus coverage. | Project Manager |
+| 2026-03-07 | Re-ran live Playwright verification for the Doctor route against a rebuilt local AdvisoryAI corpus (`unified-search-contextual-suggestions.live.e2e.spec.ts`) and confirmed automatic chips, grounded answer framing, and follow-up chips over real search data. | Test Automation |
+| 2026-03-08 | Completed priority-route rollout verification across findings, policy, doctor, timeline, and releases. Added optional `search_self_serve_*` browser telemetry markers, route-aware fixture coverage, and a dedicated Playwright operator-journey suite (`unified-search-priority-route-journeys.e2e.spec.ts`). Focused Angular coverage passed `37/37`; the combined search Playwright pack passed `22/22`. | Developer / Test Automation |
+
+## Decisions & Risks
+- Decision: rollout should prioritize high-frequency operator pages before broad route coverage.
+- Decision: page teams own their self-serve question sets; platform code owns composition and safety rails.
+- Decision: mock-backed Playwright remains acceptable for pages without live corpus parity, but rollout is incomplete until at least one priority route is verified against a rebuilt local corpus.
+- Risk: inconsistent page adoption would make self-serve feel random across the product.
+- Mitigation: maintain a priority rollout list and explicit page-ownership rules.
+- Risk: adding guided actions without verification can create shallow or broken handoffs.
+- Mitigation: require Playwright coverage for each high-value journey.
+- Risk: live-ingested routes can drift from mocked expectations as ingestion adapters evolve.
+- Mitigation: document route parity and keep at least one live route in the regular regression pack.
+- Decision: self-serve gap telemetry remains optional and client-side; it must never block or alter search behavior when telemetry is disabled.
+- Risk: shared-worktree frontend errors from unrelated modules can interfere with pointer-based E2E interactions on affected routes.
+- Mitigation: keep search rollout assertions scoped to the search surface and avoid changing unrelated feature files owned by other agents.
+
+## Next Checkpoints
+- 2026-03-12: Priority page rollout started after answer contract freeze.
+- 2026-03-14: Guided handoff journeys verified in Playwright.
+- 2026-03-16: Gap telemetry reviewed for next backlog cut.

docs-archived/implplan/SPRINT_20260307_020_FE_overflow_answer_consumption_and_chip_viability.md

@@ -0,0 +1,89 @@
+# Sprint 20260307-020 - FE Overflow Answer Consumption and Chip Viability
+
+## Topic & Scope
+- Consume the additive unified-search response contract so the UI presents current-scope results first and out-of-scope overflow only when warranted.
+- Stop rendering dead page chips when backend coverage says the active corpus cannot answer them.
+- Keep search zero-learning: no explicit scope selector, no explicit mode selector, and no recover panel.
+- Working directory: `src/Web/StellaOps.Web`.
+- Expected evidence: Angular unit tests, Playwright search UX tests, updated UI docs, and a scoped commit.
+
+## Dependencies & Concurrency
+- Depends on `SPRINT_20260307_019_AdvisoryAI_implicit_scope_weighting_and_suggestion_viability.md`.
+- Safe parallelism: unrelated Web feature work can continue as long as it does not touch `global-search` or unified-search API contracts.
+
+## Documentation Prerequisites
+- `docs/modules/ui/search-zero-learning-primary-entry.md`
+- `docs/modules/advisory-ai/unified-search-architecture.md`
+- `docs/modules/advisory-ai/knowledge-search.md`
+
+## Delivery Tracker
+
+### FE-ZL-001 - Consume primary and overflow search sections
+Status: DONE
+Dependency: none
+Owners: Developer (Frontend)
+Task description:
+- Update the unified-search client and search bar component to consume backend primary/overflow cards and answer metadata.
+- Present current-scope-biased cards first and clearly label overflow results without asking the user to manage scope manually.
+
+Completion criteria:
+- [x] The frontend consumes additive overflow/coverage fields without breaking legacy fallback behavior.
+- [x] Primary cards render before overflow cards when both exist.
+- [x] Overflow results are visually subordinate and only shown when present.
+
+### FE-ZL-002 - Use backend answer framing instead of frontend heuristics
+Status: DONE
+Dependency: FE-ZL-001
+Owners: Developer (Frontend)
+Task description:
+- Replace the current frontend-only answer heuristics with backend-provided answer status, summary, citations, and follow-up questions.
+- Preserve a deterministic fallback when the backend omits the new answer frame.
+
+Completion criteria:
+- [x] Search answer panels prefer backend answer data.
+- [x] Frontend fallback logic remains available for older or degraded responses.
+- [x] `Did you mean` remains directly under the input/result header.
+
+### FE-ZL-003 - Suppress dead contextual chips using backend coverage
+Status: DONE
+Dependency: FE-ZL-001
+Owners: Developer (Frontend)
+Task description:
+- Preflight contextual/page chips against backend coverage so suggestions that cannot execute are not rendered.
+- Preserve useful fallback chips only when the backend confirms a non-empty relevant corpus or candidate set.
+
+Completion criteria:
+- [x] Contextual chips are hidden when coverage says their domain/query family is empty.
+- [x] Clicking any rendered contextual chip yields visible results or a backend-issued clarify frame.
+- [x] Search history still records only successful result-bearing searches.
+
+### FE-ZL-004 - Targeted frontend verification
+Status: DONE
+Dependency: FE-ZL-003
+Owners: Test Automation
+Task description:
+- Add unit and Playwright coverage for overflow sections, backend answer consumption, and chip suppression.
+
+Completion criteria:
+- [x] Angular tests cover overflow rendering and backend answer consumption.
+- [x] Playwright covers chip suppression and mixed primary/overflow result presentation.
+- [x] Execution log records commands and outcomes.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-07 | Sprint created to consume backend zero-learning search contracts in the Web primary entry. | Project Manager |
+| 2026-03-07 | Implemented additive FE contract consumption: backend `contextAnswer` now drives the answer-first panel when present, overflow results render as a secondary section, and domain-filter teaching controls are no longer shown. | Developer |
+| 2026-03-07 | Added suggestion viability preflight for empty-state contextual chips/common questions so dead suggestions are suppressed before render while legacy fallback behavior remains intact if the endpoint is unavailable. | Developer |
+| 2026-03-07 | Verification: `npm test -- --include src/tests/global_search/global-search.component.spec.ts` passed (`24/24`). `npx playwright test tests/e2e/unified-search-contextual-suggestions.e2e.spec.ts tests/e2e/unified-search-self-serve-answer-panel.e2e.spec.ts tests/e2e/unified-search-experience-quality.e2e.spec.ts --config playwright.config.ts` passed (`13/13`). | Test Automation |
+
+## Decisions & Risks
+- Decision: chip viability is enforced from backend coverage signals, not static page metadata alone.
+- Decision: backend answer framing is preferred, with frontend heuristics retained only as backward-compatible fallback.
+- Decision: overflow results replace manual result-domain refinements in the primary search experience. The user sees a weighted answer first and any cross-scope evidence second, instead of being asked to filter the result set manually.
+- Risk: mixed deployments may return older unified-search payloads during rollout.
+- Mitigation: keep all new frontend contract usage additive and optional.
+
+## Next Checkpoints
+- 2026-03-09: Start FE-ZL-001 and FE-ZL-002 after backend phase 2 lands.
+- 2026-03-09: Add Playwright coverage for overflow and viable-chip rendering.