feat: agent fixes + ADR consolidation + UI/lib enhancements (#924, #928, #929) (#931)

* docs(adr): renumber ADRs to 001-027 and consolidate boundaries

- Renumber ADR catalog: 001 (Python 3.13) through 027 (Truth Layer)

- Consolidate ADRs: 003 (adapter+boundaries+connector registry), 004 (FastAPI+REST/MCP), 007 (memory tiers+builder+partitioning+namespace), 017 (azd+Flux GitOps), 024 (communication+isolation+async)

- Remove orphan adr-021-azd-first-deployment.md (duplicate of consolidated 017)

- Sanitize historical prose: remove obsolete ADR-NNN breadcrumbs from consolidated docs

- Update CHANGELOG, CONTRIBUTING, .gitignore, governance docs to canonical numbers

- Update memories/repo/architecture-decisions.md to current 27-ADR scheme

* feat(lib): foundry agent improvements + factory endpoint hardening

- foundry.py: enhanced Foundry agent client (163 line delta) — pipeline robustness

- app_factory.py + endpoints.py + foundry_lifecycle.py: factory hardening, lifecycle hooks

- prompt_loader.py: prompt loading enhancements

- mcp/server.py: minor MCP server tweak

- Tests: +84 lines factory endpoints, +447 lines foundry coverage

* chore(infra): align deploy workflow + bicep + helm release with ADR-017/021/026

- deploy-azd.yml: workflow updates

- shared-infrastructure.bicep: ADR ref updates and infra alignment

- render-helm.sh: ADR ref updates

- ecommerce-catalog-search.yaml HelmRelease: minor adjustments

* feat(ui): agent invocation telemetry hook + streaming service + semantic search hardening

* feat(ui): demo scenarios, agent telemetry, product graph + admin enhancements

- New: scenarios pages, AdminLaunchpad, demo components, agent invocation telemetry, fleet summary, agent streaming service

- Enhanced: ProductGraphCanvas, AgentRobot/AgentRobotOverlay, Navigation, AdminServiceDashboardPage

- Hooks: useAgentInvocationTelemetry, useFleetSummary, expanded useAgentMonitor/useEnrichmentMonitor

- API proxy + base URL resolver hardening

- Tests: ProductGraphCanvas, AgentProfileDrawer, productService unit tests; cockpit-readiness, dark-mode-regression, demo-narrative e2e specs

- Issues #924, #928, #929 (agent-fixes)

* feat(ui): commerce cockpit polish, thinking bubble, robot intro, dark mode + test hardening

- Add ThinkingBubble and RobotScatterIntro components
- Product similarity hook for related items
- Commerce agent layout test coverage
- Dark mode regression spec fixes
- API proxy env test expansion
- Agent profiles and streaming service improvements
- Theme context and global CSS refinements

Author: Cataldir

.github/agents/Truth_Layer_Pipeline.agent.md

@@ -77,12 +77,12 @@ class TruthIngestionAgent(BaseRetailAgent):
         ...
 ```
 
-### SLM-First Routing (ADR-013)
+### SLM-First Routing (ADR-010)
 - All agents use SLM first (fast model, e.g., `gpt-5-nano`)
 - Automatic escalation to LLM when complexity requires it
 - Configure via `FoundryAgentConfig` with `FOUNDRY_AGENT_ID_FAST` / `FOUNDRY_AGENT_ID_RICH`
 
-### MCP Tool Exposition (ADR-010)
+### MCP Tool Exposition (ADR-004)
 - Register domain MCP tools via `FastAPIMCPServer.add_tool(path, handler)`
 - MCP tools return structured dicts for agent-to-agent communication
 - Tools are mounted at `/mcp` prefix
@@ -157,7 +157,7 @@ Add 6 route modules to `apps/crud-service/src/crud_service/routes/`:
 3. **Every enrichment must include**: confidence score, source model ID, evidence references
 4. **Immutable audit trail** — every state change produces an `AuditEvent`
 5. **All services follow `build_service_app()`** pattern with FoundryAgentConfig for SLM/LLM
-6. Agents expose both **REST endpoints AND MCP tools** (ADR-010)
+6. Agents expose both **REST endpoints AND MCP tools** (ADR-004)
 7. **Tests required**: unit tests in each `tests/` directory, integration tests for cross-service flows
 8. Follow **PEP 8** strictly; use `pyproject.toml` with `uv`
 9. Each new app needs a `Dockerfile`, `pyproject.toml`, and proper package structure

.github/agents/code-guidelines-agent.agent.md

@@ -2,7 +2,7 @@
 name: CodeReviewer
 description: "Reviews and writes code for educational content (books, papers, courses, notebooks) ensuring executability, decomposition (≤20 lines per block), prose explanations for every function, and language-specific standards (Python type hints, TypeScript interfaces, Go error handling)."
 argument-hint: "Review the code examples in Chapter 4 of the AI Operations book for executability, decomposition limits, educational clarity, and version currency"
-tools: ['execute', 'read', 'edit', 'search', 'web', 'agent', 'todo']
+tools: [execute/runNotebookCell, execute/getTerminalOutput, execute/killTerminal, execute/sendToTerminal, execute/runTask, execute/createAndRunTask, execute/runInTerminal, execute/runTests, read/getNotebookSummary, read/problems, read/readFile, read/viewImage, read/readNotebookCellOutput, read/terminalSelection, read/terminalLastCommand, read/getTaskOutput, agent/runSubagent, edit/createDirectory, edit/createFile, edit/createJupyterNotebook, edit/editFiles, edit/editNotebook, edit/rename, search/changes, search/codebase, search/fileSearch, search/listDirectory, search/textSearch, search/usages, web/fetch, web/githubRepo, azure-mcp/search, workflow-ops-server/assess_report_quality, workflow-ops-server/classify_signals, workflow-ops-server/collect_github_contributions, workflow-ops-server/compose_from_dailies, workflow-ops-server/query_dataverse_opportunities, workflow-ops-server/retitle_copilot_sidebar_chats, workflow-ops-server/retrieve_historical_context, workflow-ops-server/retrieve_live_context, workflow-ops-server/search_copilot_sidebar_chats, workflow-ops-server/smoke_runtime, workflow-ops-server/validate_contracts, workflow-ops-server/validate_journal_structure, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, todo]
 user-invocable: true
 disable-model-invocation: false
 ---

.github/agents/data/holiday-peak-hub-pr-review.md

@@ -14,10 +14,10 @@ Every PR closure MUST involve the Architecture_Patterns agent. This is non-negot
 1. **Before approving any PR**, invoke or defer to the `Architecture_Patterns` agent to validate:
    - Adherence to ADRs (Architecture Decision Records) in `docs/architecture/adrs/`
    - Correct use of `BaseAdapter`, `BaseRetailAgent`, `AgentBuilder` patterns
-   - Event-driven patterns follow ADR-005 and ADR-007 (Saga/Choreography)
-   - Connector patterns follow ADR-024 (Connector Registry)
-   - Memory tier usage follows ADR-008 and ADR-014
-   - MCP tool exposition follows ADR-010
+   - Event-driven patterns follow ADR-006 (Saga/Choreography)
+   - Connector patterns follow ADR-003 (Connector Registry)
+   - Memory tier usage follows ADR-007
+   - MCP tool exposition follows ADR-004
    - Data enrichment guardrails are enforced (no AI-generated content without source data)
 
 2. **Architecture_Patterns agent must confirm**:
@@ -149,4 +149,4 @@ If `apps/crud-service/` changes:
 Default: **Squash and merge** (preferred for feature branches).
 
 ### Branch Naming Convention
-Follows ADR-022 pattern. Branches are ephemeral — delete after merge.
+Follows ADR-018 pattern. Branches are ephemeral — delete after merge.

.github/agents/data/holiday-peak-hub.yaml

@@ -37,15 +37,15 @@ structure:
 adrs:
   - id: ADR-003
     rule: All retail integrations via adapters — agents NEVER call retailer APIs directly
-  - id: ADR-005
+  - id: ADR-004
     rule: FastAPI + MCP for dual exposition
-  - id: ADR-008
+  - id: ADR-007
     rule: Three-tier memory (Redis/Cosmos/Blob)
-  - id: ADR-010
+  - id: ADR-004
     rule: Dual exposition (REST + MCP)
-  - id: ADR-012
+  - id: ADR-003
     rule: Domain-driven adapter boundaries, composition over inheritance
-  - id: ADR-013
+  - id: ADR-010
     rule: SLM-first routing
 
 existing_connectors:

.github/agents/pr-evaluator.agent.md

@@ -288,9 +288,9 @@ Check the issue's task list against PR changes:
 
 ### Step 4: Architecture Sign-off
 Coordinate with Architecture_Patterns agent:
-- Event schemas follow ADR-005 patterns
+- Event schemas follow ADR-006 patterns
 - Webhook → Event Hub → Consumer flow matches the documented architecture
-- Idempotency pattern aligns with ADR-007 (Saga/Choreography at-least-once delivery)
+- Idempotency pattern aligns with ADR-006 (Saga/Choreography at-least-once delivery)
 - No AI content generation without source data (guardrails ADR)
 
 ### Step 5: Merge
@@ -336,17 +336,17 @@ holiday-peak-hub/
 | ADR | Title | Impact on PR Review |
 |-----|-------|---------------------|
 | ADR-003 | Adapter Pattern | All integrations via adapters, never direct API calls |
-| ADR-005 | FastAPI + MCP | Dual exposition pattern |
-| ADR-007 | Saga/Choreography | Event-driven patterns, at-least-once delivery |
-| ADR-008 | Memory Tiers | Redis/Cosmos/Blob usage |
-| ADR-010 | REST + MCP Exposition | Endpoint conventions |
-| ADR-012 | Adapter Boundaries | Domain-driven, composition over inheritance |
-| ADR-013 | Model Routing | SLM-first, upgrade to LLM |
-| ADR-014 | Memory Partitioning | Partition key strategy |
-| ADR-021 | azd-first Deployment | Deployment workflow conventions |
-| ADR-022 | Branch Naming | Branch prefix + issue ID |
-| ADR-024 | Connector Registry | Connector discovery + health patterns |
-| ADR-025 | Product Truth Layer | Truth layer data flow |
+| ADR-004 | FastAPI + MCP | Dual exposition pattern |
+| ADR-006 | Saga/Choreography | Event-driven patterns, at-least-once delivery |
+| ADR-007 | Memory Tiers | Redis/Cosmos/Blob usage |
+| ADR-004 | REST + MCP Exposition | Endpoint conventions |
+| ADR-003 | Adapter Boundaries | Domain-driven, composition over inheritance |
+| ADR-010 | Model Routing | SLM-first, upgrade to LLM |
+| ADR-007 | Memory Partitioning | Partition key strategy |
+| ADR-017 | azd-first Deployment | Deployment workflow conventions |
+| ADR-018 | Branch Naming | Branch prefix + issue ID |
+| ADR-003 | Connector Registry | Connector discovery + health patterns |
+| ADR-020 | Product Truth Layer | Truth layer data flow |
 
 ### CI/CD Pipeline Dependencies
 ```
@@ -385,7 +385,7 @@ manual trigger
 
 ## Branch Naming Convention
 
-Follow ADR-022: `<prefix>/<issue-id>-<short-description>`
+Follow ADR-018: `<prefix>/<issue-id>-<short-description>`
 - `feature/` — new capabilities
 - `bug/` — defect fixes
 - `hotfix/` — urgent production fixes

.github/agents/ui-agent.agent.md

@@ -2,7 +2,7 @@
 name: UIDesigner
 description: "Builds inclusive interfaces with semantic HTML, WCAG 2.2 AA/AAA compliance, CSS Grid/Flexbox/Container Queries, fluid typography (clamp), logical properties for RTL, and Core Web Vitals optimization. Supports web (Tailwind), CLI (Ink), and desktop platforms."
 argument-hint: "Audit this dashboard component for WCAG 2.2 AA compliance, optimize LCP/CLS scores, and add responsive Container Query breakpoints"
-tools: ['execute', 'read', 'edit', 'search', 'web', 'agent', 'todo']
+tools: [execute/runNotebookCell, execute/getTerminalOutput, execute/killTerminal, execute/sendToTerminal, execute/runTask, execute/createAndRunTask, execute/runInTerminal, execute/runTests, execute/testFailure, read/getNotebookSummary, read/problems, read/readFile, read/viewImage, read/readNotebookCellOutput, read/terminalSelection, read/terminalLastCommand, read/getTaskOutput, agent/runSubagent, edit/createDirectory, edit/createFile, edit/createJupyterNotebook, edit/editFiles, edit/editNotebook, edit/rename, search/changes, search/codebase, search/fileSearch, search/listDirectory, search/textSearch, search/usages, web/fetch, web/githubRepo, azure-mcp/search, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, todo]
 user-invocable: true
 disable-model-invocation: false
 ---

.github/copilot-instructions.md

@@ -97,7 +97,7 @@ Use this mapping to know the current vs. former names—so you can correctly int
 
 ## Git Branch Naming Convention
 
-- Follow the branch naming convention defined in [ADR-022](../docs/architecture/adrs/adr-022-branch-naming-convention.md).
+- Follow the branch naming convention defined in [ADR-018](../docs/architecture/adrs/adr-018-branch-naming-convention.md).
 - **Branch prefixes**: `feature/`, `issue/`, `bug/`, `hotfix/`, `docs/`, `chore/`.
 - **Format**: `<prefix>/<issue-id>-<short-description>` (e.g., `feature/42-cart-intelligence`).
 - Always use **lowercase** with **hyphens** as word separators.

.github/prompts/fix-issues-pipeline.prompt.md

@@ -54,7 +54,7 @@ Investigate and resolve the described issue through a fully tracked GitHub workf
 ## Phase 3: Branch & Implementation
 
 1. **Create Branch** — From the default branch (`main`), create:
-   - `bug/<issue-number>-<short-description>` (per ADR-022 branch naming convention)
+   - `bug/<issue-number>-<short-description>` (per ADR-018 branch naming convention)
 
 2. **Implement Fix** — Delegate to the appropriate specialist agents via `#runSubagent`:
 

.github/workflows/deploy-azd.yml

@@ -440,7 +440,7 @@ jobs:
           azd env set KEDA_ENABLED true -e "${{ inputs.environment }}"
           # PostgreSQL auth: use password for dev until Entra AD admin is configured
           # in Bicep (administrators param on AVM PostgreSQL module). Enabling
-          # activeDirectoryAuth without an admin has no effect — see ADR-033 follow-up.
+          # activeDirectoryAuth without an admin has no effect — see ADR-017 follow-up.
           azd env set POSTGRES_AUTH_MODE password -e "${{ inputs.environment }}"
 
       - name: Install kubelogin
@@ -2025,7 +2025,7 @@ jobs:
           export AZURE_CLIENT_ID="${WORKLOAD_AZURE_CLIENT_ID}"
           CRUD_IMAGE_REF=$(tr -d '\r\n' < "${RUNNER_TEMP}/tested-image/crud-service/image-ref.txt")
 
-          # Phase B (ADR-033): Render only — Flux reconciles from Git
+          # Phase B (ADR-017): Render only — Flux reconciles from Git
           export SERVICE_CRUD_SERVICE_IMAGE_NAME="$CRUD_IMAGE_REF"
           bash .infra/azd/hooks/render-helm.sh crud-service
           echo "Rendered CRUD manifest for Flux reconciliation (image: ${CRUD_IMAGE_REF})."
@@ -2675,7 +2675,7 @@ jobs:
           SERVICE_IMAGE_VAR_NAME="SERVICE_$(printf '%s' "$SERVICE_NAME" | tr '[:lower:]-' '[:upper:]_')_IMAGE_NAME"
           export "${SERVICE_IMAGE_VAR_NAME}=${IMAGE_REF}"
 
-          # Phase B (ADR-033): Render only — Flux reconciles from Git
+          # Phase B (ADR-017): Render only — Flux reconciles from Git
           bash .infra/azd/hooks/render-helm.sh "$SERVICE_NAME"
           echo "Rendered ${SERVICE_NAME} manifest for Flux reconciliation (image: ${IMAGE_REF})."
         env:
@@ -3432,7 +3432,7 @@ jobs:
           SHARED_GATEWAY_NAME="holiday-peak-agc"
           SHARED_GATEWAY_NAMESPACE="holiday-peak-crud"
 
-          # Architecturally approved contract (ADR-033):
+          # Architecturally approved contract (ADR-021):
           #   - Shared AGC uses an in-cluster ApplicationLoadBalancer CR that the
           #     ALB controller manages — creating and maintaining the ARM
           #     trafficController resource automatically.
@@ -3465,7 +3465,7 @@ jobs:
 
           mapfile -t TRAFFIC_CONTROLLER_IDS < <(az resource list -g "$AKS_NODE_RESOURCE_GROUP" --resource-type Microsoft.ServiceNetworking/trafficControllers --query '[].id' -o tsv)
           if [ "${#TRAFFIC_CONTROLLER_IDS[@]}" -eq 0 ]; then
-            echo "::error::No Azure Application Gateway for Containers trafficControllers were found in node resource group '$AKS_NODE_RESOURCE_GROUP'. Per ADR-033 the shared ALB must be ARM-provisioned by Bicep." >&2
+            echo "::error::No Azure Application Gateway for Containers trafficControllers were found in node resource group '$AKS_NODE_RESOURCE_GROUP'. Per ADR-021 the shared ALB must be ARM-provisioned by Bicep." >&2
             exit 1
           fi
 
@@ -3527,7 +3527,7 @@ jobs:
 
           echo "Live shared Gateway evidence: ${GATEWAY_CONTRACT_EVIDENCE}"
 
-          # ADR-033 (updated): require in-cluster managed ALB binding via alb-name/alb-namespace.
+          # ADR-021 (updated): require in-cluster managed ALB binding via alb-name/alb-namespace.
           # The BYO alb-id annotation mode is no longer used — ALB controller manages the TC lifecycle.
           if [ -n "$AGC_SHARED_ALB_ID" ]; then
             echo "::warning::Live shared Gateway '$SHARED_GATEWAY_NAME' carries a BYO alb-id annotation ('${AGC_SHARED_ALB_ID}'). The approved binding mode is now managed (alb-name/alb-namespace). ${GATEWAY_CONTRACT_EVIDENCE}"

.gitignore

@@ -198,7 +198,7 @@ DocProject/Help/html
 # Click-Once directory
 publish/
 
-# Flux reconciles rendered manifests from Git (ADR-033).
+# Flux reconciles rendered manifests from Git (ADR-017).
 # Only kustomization.yaml is tracked; per-service all.yaml files are committed
 # by the CI deploy workflow after render-helm.sh generates them.
 # .kubernetes/rendered/  — no longer ignored