stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

Archive completed search foundation sprints

Browse Source
This commit is contained in:
master
2026-03-08 00:16:35 +02:00
parent a6187c70b4
commit 8ee40b56e9
3 changed files with 28 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

178
docs/implplan/SPRINT_20260306_001_Web_contextual_search_suggestions.md
View File

@@ -1,178 +0,0 @@
# Sprint 20260306-001 - Contextual Search Suggestions (Page + Last Action)
## Topic & Scope
- Extend global search and AdvisoryAI suggestion behavior so prompts/chips are influenced by the current page and the user's latest meaningful action.
- Activate existing backend ambient-context capabilities end-to-end by sending ambient payloads from the Web client.
- Add deterministic, bounded context-aware refinement logic without breaking offline-first behavior.
- Working directory: `src/Web/StellaOps.Web`.
- Expected evidence: Angular unit tests, AdvisoryAI unit/integration tests, updated module docs, and sprint execution log artifacts.
## Dependencies & Concurrency
- Upstream contracts and code paths:
- `src/Web/StellaOps.Web/src/app/layout/global-search/global-search.component.ts`
- `src/Web/StellaOps.Web/src/app/core/services/ambient-context.service.ts`
- `src/Web/StellaOps.Web/src/app/core/api/unified-search.client.ts`
- `src/AdvisoryAI/StellaOps.AdvisoryAI/UnifiedSearch/UnifiedSearchModels.cs`
- `src/AdvisoryAI/StellaOps.AdvisoryAI/UnifiedSearch/Context/AmbientContextProcessor.cs`
- `src/AdvisoryAI/StellaOps.AdvisoryAI.WebService/Endpoints/UnifiedSearchEndpoints.cs`
- Cross-module edits are explicitly allowed for this sprint in:
- `src/AdvisoryAI/**`
- `docs/modules/ui/**`
- `docs/modules/advisory-ai/**`
- Safe parallelism:
- FE context-capture and FE rendering tasks can run in parallel with backend DTO expansion once ambient payload shape is frozen.
- Backend ranking/refinement logic should start only after DTO contract freeze.
## Documentation Prerequisites
- `docs/modules/ui/architecture.md`
- `docs/modules/advisory-ai/unified-search-architecture.md`
- `docs/modules/advisory-ai/knowledge-search.md`
- `docs/modules/ui/implementation_plan.md`
- `docs/modules/advisory-ai/implementation_plan.md`
## Delivery Tracker
### WEB-CTX-001 - Baseline behavior and gap mapping
Status: DONE
Dependency: none
Owners: Project Manager, Developer (FE), Developer (AdvisoryAI)
Task description:
- Capture the current behavior matrix for search suggestions and chat-to-search handoff.
- Document concrete gaps discovered in implementation: no ambient payload emitted by Web client, route-only suggestion chips, no "last action" signal, and route-prefix mismatches between FE and AdvisoryAI route-domain mappings.
Completion criteria:
- [x] Gap matrix is written in sprint notes with file references.
- [x] Confirmed list of required contract changes is frozen before implementation tasks start.
### WEB-CTX-002 - FE ambient context capture (page + last action)
Status: DONE
Dependency: WEB-CTX-001
Owners: Developer (FE)
Task description:
- Extend FE context services to track and expose:
- current route
- recent search terms
- visible entity keys (bounded set)
- session id for follow-up search continuity
- last action metadata (surface, action type, domain/entity, timestamp, optional query seed)
- Wire context capture from key UX surfaces: global search result actions, chat "Search for more", chat "Search related", and Ask AI handoff actions.
Completion criteria:
- [x] Ambient context provider exposes deterministic snapshot API used by search.
- [x] Last action tracking is bounded by TTL and max-history limits.
- [x] Unit tests cover action capture and decay/reset semantics.
### WEB-CTX-003 - FE -> AdvisoryAI contract activation for ambient payload
Status: DONE
Dependency: WEB-CTX-002
Owners: Developer (FE), Developer (AdvisoryAI)
Task description:
- Extend `UnifiedSearchClient` request DTO and serialization to include `ambient` object.
- Include route, session, visible entities, recent queries, and last action fields in `/v1/search/query` requests.
- Preserve backward compatibility if backend field support is partially deployed.
Completion criteria:
- [x] Search requests include ambient payload when context is available.
- [x] Existing search behavior remains functional when ambient payload is absent.
- [x] FE tests assert payload shape sent to `/api/v1/search/query`.
### WEB-CTX-004 - AdvisoryAI ambient contract and processor extension
Status: TODO
Dependency: WEB-CTX-003
Owners: Developer (AdvisoryAI)
Task description:
- Extend `AmbientContext`/API DTO contracts to support last action hints.
- Normalize and validate new ambient fields in `UnifiedSearchEndpoints`.
- Update `AmbientContextProcessor` and related flow in `UnifiedSearchService` to apply deterministic boosts/refinements from last action context.
- Align route-domain mapping prefixes with current FE routing patterns.
Completion criteria:
- [ ] Backend accepts and normalizes last-action ambient metadata.
- [ ] Route mapping parity tests cover FE route prefixes currently in use.
- [ ] Unit/integration tests verify context-aware boosts/refinements are deterministic.
### WEB-CTX-005 - Context-aware suggestion UX updates
Status: DOING
Dependency: WEB-CTX-004
Owners: Developer (FE), UX
Task description:
- Update global search empty-state and sparse-result suggestion chips so they blend:
- route-aware defaults
- last-action-aware suggestions
- backend refinements/suggestions when present
- Ensure chat onboarding suggestions remain consistent with shared context rules.
Completion criteria:
- [ ] Empty-state suggestion chips adapt to route + last action.
- [ ] No-results and sparse-results views surface contextual refinements clearly.
- [ ] Accessibility and keyboard navigation behavior remains intact.
### WEB-CTX-006 - Quality telemetry and guardrails
Status: TODO
Dependency: WEB-CTX-004
Owners: Developer (FE), Developer (AdvisoryAI)
Task description:
- Add bounded telemetry markers to evaluate contextual suggestion usefulness without storing sensitive raw prompts beyond existing policy.
- Ensure no unbounded growth in in-memory/session context stores.
- Keep deterministic ordering and offline behavior guarantees.
Completion criteria:
- [ ] Telemetry and logs distinguish contextual vs non-contextual suggestion paths.
- [ ] Privacy posture for stored query/action metadata is documented and validated.
- [ ] No new external dependencies introduced.
### WEB-CTX-007 - Docs sync and rollout plan
Status: DOING
Dependency: WEB-CTX-005
Owners: Documentation author, Project Manager
Task description:
- Update module docs with final contract and behavior:
- `docs/modules/ui/architecture.md`
- `docs/modules/advisory-ai/unified-search-architecture.md`
- `docs/modules/advisory-ai/knowledge-search.md`
- Record rollout strategy (feature flag/canary, fallback behavior, success metrics) and decision log.
Completion criteria:
- [ ] Docs reflect final API payload and UI behavior.
- [ ] Sprint Decisions & Risks includes rollout gates and fallback plan.
- [ ] Execution log captures implementation and verification evidence links.
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-03-06 | Sprint created from code-and-doc investigation of global search and AdvisoryAI ambient context flow. | Project Manager |
| 2026-03-06 | WEB-CTX-001 marked DONE after baseline gap mapping; WEB-CTX-002 started for FE context capture implementation. | Developer (FE) |
| 2026-03-06 | Implemented FE route + last-action ambient capture, wired chat/search action capture, and emitted ambient payloads from global search requests. | Developer (FE) |
| 2026-03-06 | Verified FE behavior via targeted unit tests: `ambient-context.service.spec.ts`, `global-search.component.spec.ts`, `chat-message.component.spec.ts` (23/23 passing). | Test Automation |
| 2026-03-06 | Added Playwright E2E coverage for contextual suggestions and ambient payload propagation (`tests/e2e/unified-search-contextual-suggestions.e2e.spec.ts`): 3/3 passing. | Test Automation |
| 2026-03-06 | Upgraded suggestion logic to include strategic non-obvious cross-domain prompts per page scope and action-aware variants after user interactions. | Developer (FE) |
| 2026-03-06 | Added typed chip-context registry contract (`search-context.registry.ts`) and shifted suggestion selection to route-context arrays + bounded last-few-action prioritization + deterministic rotation. | Developer (FE) |
| 2026-03-06 | Synced architecture docs for automatic page-open suggestions and ambient `lastAction` contract: `docs/modules/ui/architecture.md`, `docs/modules/advisory-ai/knowledge-search.md`, `docs/modules/advisory-ai/unified-search-architecture.md`. | Documentation author |
| 2026-03-06 | Added UI governance rule for chip ownership and page-context interface in `docs/modules/ui/search-chip-context-contract.md`. | Documentation author |
| 2026-03-06 | Added exhaustive Playwright query-matrix suite (`tests/e2e/unified-search-exhaustive-matrix.e2e.spec.ts`) generating 1200 deterministic query types split into 6 strict 200-query batches; verified 100% success across all batches. | Test Automation |
| 2026-03-06 | Migrated default hostname from 127.1.0.1 to stella-ops.local across envsettings-override, proxy.conf, playwright config, perf fixtures, README, and smoke scripts. | Developer (FE) |
| 2026-03-06 | QA iteration: 23/23 sprint unit tests pass (ambient-context 6, global-search 11, chat-message 6). Live behavioral verification via Playwright confirms contextual placeholders and suggestion chips adapt per page (dashboard/triage/policy/scanning). OIDC login flow works end-to-end at stella-ops.local. | QA |
| 2026-03-07 | Added ingestion-backed contextual suggestion verification for the Doctor route: local rebuild order (`/v1/advisory-ai/index/rebuild` then `/v1/search/index/rebuild`) was exercised and `unified-search-contextual-suggestions.live.e2e.spec.ts` proved page-open chips and chip-triggered search over real ingested search data. | Test Automation |
## Decisions & Risks
- Decision needed: whether route context should remain a hard domain filter in FE (`buildContextFilter`) or become a soft ranking hint only via ambient payload.
- Decision needed: final schema for `lastAction` ambient metadata and retention policy in FE memory/session scope.
- Decision: FE emits `ambient.lastAction` now as a forward-compatible field; current backend deployments may ignore it without regressing behavior.
- Decision: chip definitions are now governed by typed context arrays (`SEARCH_CONTEXT_DEFINITIONS`) and an explicit page-level interface contract (`SearchContextComponent`) instead of ad-hoc route conditionals.
- Decision: exhaustive >1000 query E2E coverage now runs as 6 strict batches of 200 queries each, resetting page state between batches and enforcing 100% per-batch success.
- Decision: contextual suggestion verification now includes one live-ingested route (Doctor/knowledge) in addition to mock-backed regression suites.
- Docs updated: `docs/modules/ui/architecture.md`, `docs/modules/ui/search-chip-context-contract.md`, `docs/modules/advisory-ai/knowledge-search.md`, `docs/modules/advisory-ai/unified-search-architecture.md`.
- Risk: stale action context may bias suggestions toward irrelevant domains.
- Mitigation: TTL + bounded history + explicit reset on session boundaries.
- Risk: route-prefix drift between FE and backend route-domain maps can silently reduce context quality.
- Mitigation: shared route mapping tests and explicit parity checks.
- Risk: mocked suggestion suites can miss ingestion/corpus regressions.
- Mitigation: keep a live-ingested Playwright lane and record rebuild/query evidence in the search sprints.
- Risk: privacy leakage if raw action labels/queries are persisted beyond current controls.
- Mitigation: preserve hashed analytics and limit persisted raw content to existing approved history paths only.
## Next Checkpoints
- 2026-03-08: Contract freeze for FE ambient payload and AdvisoryAI DTO updates.
- 2026-03-10: FE context-capture + payload emission complete with unit tests.
- 2026-03-12: AdvisoryAI processor/refinement updates complete with integration tests.
- 2026-03-13: Docs sync and rollout readiness review.

136
docs/implplan/SPRINT_20260306_002_FE_search_advisory_quality_ux.md
View File

@@ -1,136 +0,0 @@
# Sprint 20260306-002 - Search and Advisory Quality UX
## Topic & Scope
- Upgrade global search and AdvisoryAI UX from "smart suggestions" to "explainable operator guidance" with visible context, rationale, and next-step framing.
- Make contextual search state legible: current page, active domain, and latest meaningful action should be visible in the search surface.
- Improve suggestion quality UX with richer chips that explain why they are being suggested and what type of action they represent.
- Working directory: `src/Web/StellaOps.Web`.
- Expected evidence: Angular unit tests, Playwright behavioral tests, updated UI docs, and sprint execution log entries.
## Dependencies & Concurrency
- Depends on `docs/implplan/SPRINT_20260306_001_Web_contextual_search_suggestions.md` for ambient context capture and chip registry groundwork.
- Upstream implementation points:
- `src/Web/StellaOps.Web/src/app/layout/global-search/global-search.component.ts`
- `src/Web/StellaOps.Web/src/app/core/services/ambient-context.service.ts`
- `src/Web/StellaOps.Web/src/app/core/services/search-context.registry.ts`
- `src/Web/StellaOps.Web/src/app/features/advisory-ai/chat/chat-message.component.ts`
- Safe parallelism:
- UI presentation work can run in parallel with docs updates once chip-view contract is frozen.
- Search mode / zero-result rescue tasks should start after context-rail patterns are 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-UX-001 - Search context rail and explainable chips
Status: DONE
Dependency: none
Owners: Developer (FE), UX
Task description:
- Add a visible context rail to the global search panel that shows:
- current page context
- active domain focus
- most recent meaningful action on the current page
- Upgrade chip rendering so suggestion chips can expose rationale text and suggestion intent/category instead of showing only raw query text.
- Keep the layout compact enough for header search use while remaining legible on mobile.
Completion criteria:
- [x] Empty-state search renders a context rail with page/domain/last-action information when available.
- [x] Suggestion chips can render rationale text from the shared chip contract.
- [x] Unit and Playwright coverage validate the new UI behavior.
### FE-UX-002 - Search modes across search and AdvisoryAI
Status: DONE
Dependency: FE-UX-001
Owners: Developer (FE), UX
Task description:
- Introduce explicit operator modes for the search/advisory experience:
- `Find`
- `Explain`
- `Act`
- Use the selected mode to influence chip ordering, Ask-AI prompts, and zero-result rescue actions.
Completion criteria:
- [x] Mode switch is visible and keyboard accessible.
- [x] Search and Ask-AI handoff respect the selected mode.
- [x] Docs describe mode behavior and fallback semantics.
### FE-UX-003 - Zero-result rescue and reformulation UX
Status: DONE
Dependency: FE-UX-001
Owners: Developer (FE), UX
Task description:
- Improve no-result and sparse-result states with guided recovery actions:
- broaden scope
- search related domains
- ask AdvisoryAI to reformulate
- retry with visible entities / current page focus
Completion criteria:
- [x] Zero-result states provide at least three recovery actions.
- [x] Recovery actions record contextual intent for follow-up search quality analysis.
- [x] Playwright tests cover rescue behavior end-to-end.
### FE-UX-004 - AdvisoryAI evidence-first next-step cards
Status: DONE
Dependency: FE-UX-002
Owners: Developer (FE), Developer (AdvisoryAI), UX
Task description:
- Upgrade AdvisoryAI responses to render structured next-step cards for common operator flows:
- search deeper
- inspect evidence chain
- compare policy impact
- open timeline / graph / VEX
- Keep all actions explicit and provenance-linked.
Completion criteria:
- [x] AdvisoryAI can render at least two structured next-step card types.
- [x] Cards preserve evidence-first behavior and do not hide provenance.
- [x] Search return flows remain deterministic.
### FE-UX-005 - Docs sync and rollout notes
Status: DONE
Dependency: FE-UX-001
Owners: Documentation author, Project Manager
Task description:
- Update UI and AdvisoryAI docs with the new UX contract and rollout guidance.
- Record rationale for the chosen quality UX direction and phased delivery order.
Completion criteria:
- [x] Architecture docs reflect context rail + explainable chip behavior.
- [x] Sprint Decisions & Risks capture rollout tradeoffs.
- [x] Execution log links implementation and verification evidence.
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-03-06 | Sprint created for quality UX improvements on top of contextual search/advisory groundwork. | Project Manager |
| 2026-03-06 | FE-UX-001 started: implementing context rail and explainable suggestion chips in global search. | Developer (FE) |
| 2026-03-06 | FE-UX-001 completed: added search context rail, explainable suggestion cards, shared registry presentation/reason contract, targeted Angular tests (19/19), and Playwright contextual-suggestions verification (3/3). | Developer (FE) |
| 2026-03-06 | FE-UX-002 completed: added shared `Find`/`Explain`/`Act` mode state, keyboard-accessible mode switchers in search and AdvisoryAI, and mode-aware search-to-chat handoff prompts. | Developer (FE) |
| 2026-03-06 | FE-UX-003 completed: added zero-result rescue actions for scope broadening, related pivots, page-context retry, and AdvisoryAI reformulation; fixed search-panel focus containment so internal controls do not collapse the surface. | Developer (FE) |
| 2026-03-06 | FE-UX-004 completed: AdvisoryAI assistant messages now render evidence-first next-step cards (search, evidence, policy, context) and return structured search intent back into global search deterministically. | Developer (FE) |
| 2026-03-06 | FE-UX-005 completed: updated UI and AdvisoryAI docs, added targeted Angular coverage (39/39), and passed Playwright behavioral suites for contextual suggestions plus quality UX flows (7/7). | Developer (FE) |
## Decisions & Risks
- Decision: the first quality UX slice will prioritize explainability over more hidden ranking logic.
- Decision: chip rationale should come from the shared registry/service contract, not component-local hardcoding.
- Decision: executable suggestion text and visible rationale must stay separate so clicking a chip always submits only the intended query string.
- Decision: search/advisory mode is a shared operator state (`Find`, `Explain`, `Act`) and not a local cosmetic toggle; prompts, chip ranking, and rescue actions all consume the same mode service.
- Decision: focus transitions inside the global-search surface must not collapse the panel; mode switches, scope toggles, and rescue buttons are part of the same command surface.
- Decision: AdvisoryAI next-step cards remain evidence-first by always exposing a direct evidence/open-context path in addition to search pivots.
- Risk: richer chip content may overcrowd the header search dropdown.
- Mitigation: use compact rail layout, limit visible chips, and keep rationale to a single short line.
- Risk: page/domain labels can drift from actual route behavior.
- Mitigation: derive labels from the same shared registry used for suggestion selection and context-rail presentation.
- Risk: explicit mode state can drift between search and chat if separate stores are introduced.
- Mitigation: keep a single root `SearchExperienceModeService` and verify handoff behavior in unit and Playwright coverage.
## Next Checkpoints
- 2026-03-07: FE-UX-001 through FE-UX-005 shipped and verified.
- 2026-03-09: Monitor search/advisory telemetry for rescue-action usage and mode adoption.
- 2026-03-11: Use field feedback to decide whether to add richer per-page card presets beyond search/policy/evidence/context.