Feature/cwyd v2 6626

.github/instructions/v2-backend-core.instructions.md

@@ -92,7 +92,7 @@ Citation formatting is **shared infrastructure**, not per-orchestrator code. The
 
 - **R1 — one prompt input point.** Ground through `resolve_cwyd_instructions(...)` over the shared `CWYD_DEFAULT_BODY`; the fixed `CWYD_GUARDRAIL` owns the citation directive + no-context fallback. Do not author a per-orchestrator system / grounding prompt.
 - **R2 — one response-format point.** All citation shaping lives in `v2/src/backend/core/tools/citations.py`: `format_sources_block` (client-side `[docN]` injection, used by `langgraph`) and `normalize_kb_citations` (native `【N:M†source】` → `[docN]` rewrite, used by `agent_framework`). Both emit the same inline `[docN]` marker + `Citation` model on the `citation` channel. `run()` returns `(answer, citations)` and delegates to `citations.py` — never format markers inline, never invent a citation shape.
-- **R3 — backend-agnostic formatting.** Retrieval is keyed by `index_store` (registry dispatch) but the citation format is identical for Azure AI Search and pgvector. The `agent_framework` + pgvector cell (no KB) is rejected at config (`ConfigResolutionError` → 409, ADR 0022), never given a divergent formatter.
+- **R3 — backend-agnostic formatting.** Retrieval is keyed by `index_store` (registry dispatch) but the citation format is identical for Azure AI Search and pgvector. The `agent_framework` + pgvector cell grounds app-side over `BaseSearch.search` (no KB), reusing the shared formatter (ADR 0027 supersedes the ADR 0022 rejection rule), never given a divergent formatter.
 
 ## LLM provider (Foundry IQ)
 

.github/instructions/v2-frontend.instructions.md

@@ -11,7 +11,7 @@ applyTo: "v2/src/frontend/**"
 - **Fluent UI v9** (`@fluentui/react-components` + `@fluentui/react-icons`) is the bundled component library. The MACAE re-skin (dev_plan task #34) committed the decision; new components consume Fluent primitives unless a CSS-Modules-only carve-out is explicitly justified.
 - **State management: React Context + `useReducer`.** Lightweight, zero new dep, idiomatic for the reasoning-channel fan-out. Reducers live next to their Context (chat) or page (admin) — do **not** extract reducers into `services/`. Revisit (e.g. Zustand, Redux Toolkit) only if cross-page state grows beyond what context comfortably handles.
 - **Routing: `react-router-dom` v7.** `App` mounts `<BrowserRouter>`; the active page is derived from the URL by the `<Routes>` block and navigation goes through `useNavigate()` + the `SectionPath` map (`src/models/sections.tsx`). Deep links to `/admin/*` are first-class.
-- Testing: Vitest + Testing Library. Tests live under `v2/src/tests/frontend/` mirroring `src/` (relocated from `v2/src/frontend/tests/` per ADR 0020).
+- Testing: Vitest + Testing Library. Tests live under `v2/tests/frontend/` mirroring `src/` (relocated to `v2/tests/frontend/` per ADR 0029, which supersedes ADR 0020).
 
 ## API layer (`src/api/`)
 
@@ -26,7 +26,7 @@ applyTo: "v2/src/frontend/**"
 - Folder layout: `src/services/<domain>/<service>.ts` (e.g. `services/chat/feedbackService.ts`, `services/admin/ingestService.ts`). Cross-domain primitives live under `src/services/core/` (e.g. the generic `Registry<T>`); app-shell concerns live under `src/services/app/` (e.g. `pageRegistry`, `healthService`).
 - Services are **pure TypeScript modules** — no React imports, no hooks. A service signature typically takes the data it needs plus the reducer's `dispatch` and returns `Promise<void>` or a typed result. This keeps services trivially testable and reusable across pages.
 - **Reducers stay co-located** with their Context (chat) or page (admin). Moving reducers into services inverts React's state-machine-next-to-its-consumer pattern.
-- Tests live under `v2/src/tests/frontend/services/**` mirroring the source tree.
+- Tests live under `v2/tests/frontend/services/**` mirroring the source tree.
 
 ## Factory registries
 
@@ -93,12 +93,12 @@ applyTo: "v2/src/frontend/**"
 ## Conventions
 
 - TypeScript strictness: `strict: true`, `noUncheckedIndexedAccess: true`, `exactOptionalPropertyTypes: true`. The three flags are non-negotiable — `tsconfig.json` is the single source of truth. Rationale + ADR: [v2/docs/adr/0013-frontend-strict-ts-and-tsx-everywhere.md](../../v2/docs/adr/0013-frontend-strict-ts-and-tsx-everywhere.md).
-- ESLint runs `@typescript-eslint/strict-type-checked` + `@typescript-eslint/stylistic-type-checked` on `src/**` and the relocated test tree `v2/src/tests/frontend/**`. `npm run lint` is CI-gated by [`.github/workflows/v2-frontend-checks.yml`](../workflows/v2-frontend-checks.yml) (lint → typecheck → vitest, all hard-gated, path-scoped to `v2/src/frontend/**` + `v2/src/tests/frontend/**`); any error fails the PR build. Rationale + ADR: [v2/docs/adr/0014-frontend-ci-workflow.md](../../v2/docs/adr/0014-frontend-ci-workflow.md).
-- File extension: all first-party files under `src/` and the test tree `v2/src/tests/frontend/` use `.tsx`, regardless of JSX content. Tooling configs (`vite.config.ts`, `tsconfig.json`, `tsconfig.app.json`) stay at their tool-pinned names. See [Hard Rule #11](../copilot-instructions.md) + ADR 0013 above.
-- Cross-folder imports under `src/**` and the test tree `v2/src/tests/frontend/**` use the `@/*` path alias (registered in `vite.config.ts` `resolve.alias` and `tsconfig.json` `compilerOptions.paths`). Sibling `./X` imports stay relative — the alias is for cross-folder reach, not for replacing every relative import. Parent-relative imports (`../X`, `../../X`, …) in first-party source/test files are forbidden by ESLint's built-in `no-restricted-imports` with a `^\.\./` regex pattern on the import source string (tool configs like `vite.config.ts` / `tsconfig.json` may still reference `../tests/frontend`). Rationale + ADR: [v2/docs/adr/0015-frontend-path-alias-cross-folder-imports.md](../../v2/docs/adr/0015-frontend-path-alias-cross-folder-imports.md).
+- ESLint runs `@typescript-eslint/strict-type-checked` + `@typescript-eslint/stylistic-type-checked` on `src/**` and the relocated test tree `v2/tests/frontend/**`. `npm run lint` is CI-gated by [`.github/workflows/v2-frontend-checks.yml`](../workflows/v2-frontend-checks.yml) (lint → typecheck → vitest, all hard-gated, path-scoped to `v2/src/frontend/**` + `v2/tests/frontend/**`); any error fails the PR build. Rationale + ADR: [v2/docs/adr/0014-frontend-ci-workflow.md](../../v2/docs/adr/0014-frontend-ci-workflow.md).
+- File extension: all first-party files under `src/` and the test tree `v2/tests/frontend/` use `.tsx`, regardless of JSX content. Tooling configs (`vite.config.ts`, `tsconfig.json`, `tsconfig.app.json`) stay at their tool-pinned names. See [Hard Rule #11](../copilot-instructions.md) + ADR 0013 above.
+- Cross-folder imports under `src/**` and the test tree `v2/tests/frontend/**` use the `@/*` path alias (registered in `vite.config.ts` `resolve.alias` and `tsconfig.json` `compilerOptions.paths`). Sibling `./X` imports stay relative — the alias is for cross-folder reach, not for replacing every relative import. Parent-relative imports (`../X`, `../../X`, …) in first-party source/test files are forbidden by ESLint's built-in `no-restricted-imports` with a `^\.\./` regex pattern on the import source string (tool configs like `vite.config.ts` / `tsconfig.json` may still reference `../../src/frontend/src`). Rationale + ADR: [v2/docs/adr/0015-frontend-path-alias-cross-folder-imports.md](../../v2/docs/adr/0015-frontend-path-alias-cross-folder-imports.md).
 - No `any`. Use `unknown` + type narrowing.
 - Plain CSS Modules (`*.module.css`) for component styling — no global CSS leaks. If a UI library is later adopted, prefer its idiomatic styling primitive (e.g. Fluent UI `makeStyles`) over CSS Modules for new components in that library's scope.
-- **Tests live under `v2/src/tests/frontend/`, mirroring the `src/` tree** (e.g. `src/pages/chat/ChatPage.tsx` → `v2/src/tests/frontend/pages/chat/ChatPage.test.tsx`). Every new component ships with a corresponding `<Component>.test.tsx` under the mirror tree covering at least one behavioral assertion. **Do not colocate `*.test.tsx` next to source files.** The Vitest `include` glob in `vite.config.ts` scans `../tests/frontend/**` only, so colocated tests under `src/` are silently skipped. The `@/*` alias still resolves to `src/`, so test imports of production code are unchanged by the relocation. Rationale + ADR: [v2/docs/adr/0020-frontend-tests-under-src-tests-frontend.md](../../v2/docs/adr/0020-frontend-tests-under-src-tests-frontend.md) (supersedes [ADR 0012](../../v2/docs/adr/0012-frontend-test-folder-mirror.md)).
+- **Tests live under `v2/tests/frontend/`, mirroring the `src/` tree** (e.g. `src/pages/chat/ChatPage.tsx` → `v2/tests/frontend/pages/chat/ChatPage.test.tsx`). Every new component ships with a corresponding `<Component>.test.tsx` under the mirror tree covering at least one behavioral assertion. **Do not colocate `*.test.tsx` next to source files.** The Vitest `include` glob in `v2/tests/frontend/vitest.config.ts` scans only the test package's own tree, so colocated tests under `src/` are silently skipped. The `@/*` alias still resolves to `src/`, so test imports of production code are unchanged by the relocation. Rationale + ADR: [v2/docs/adr/0029-frontend-tests-symmetric-under-tests-frontend.md](../../v2/docs/adr/0029-frontend-tests-symmetric-under-tests-frontend.md) (relocates to `v2/tests/frontend/`; supersedes [ADR 0020](../../v2/docs/adr/0020-frontend-tests-under-src-tests-frontend.md) + [ADR 0012](../../v2/docs/adr/0012-frontend-test-folder-mirror.md)).
 ## Branding / customization
 
 - All branding text/logo loaded at runtime from `/api/admin/ui-config` (backed by `active.json`). *(That endpoint lands in Phase 5 — dev_plan task #35. Until then, the placeholder shell may use a single hard-coded title; replace it the moment the endpoint exists.)*

.github/instructions/v2-tests.instructions.md

@@ -1,6 +1,6 @@
 ---
-description: "CWYD v2 testing conventions and test-first contract. Use when: editing v2/tests/**, editing v2/src/**/tests/**, editing v2/src/tests/** (relocated frontend Vitest tree), adding a pytest test, adding a vitest/jest test, configuring fixtures, mocking Foundry IQ or Azure Search, asserting on SSE events, gating coverage, or completing the test step of the implement-then-test loop."
-applyTo: "v2/tests/**,v2/src/**/tests/**,v2/src/tests/**"
+description: "CWYD v2 testing conventions and test-first contract. Use when: editing v2/tests/**, editing v2/src/**/tests/**, editing v2/tests/frontend/** (relocated frontend Vitest tree), adding a pytest test, adding a vitest/jest test, configuring fixtures, mocking Foundry IQ or Azure Search, asserting on SSE events, gating coverage, or completing the test step of the implement-then-test loop."
+applyTo: "v2/tests/**,v2/src/**/tests/**"
 ---
 
 # v2 Testing Conventions

.github/workflows/v2-frontend-checks.yml

@@ -4,17 +4,17 @@ name: v2 frontend checks (lint + typecheck + vitest)
 #
 # The v2 frontend is an npm workspace rooted at `v2/` with two members:
 #   - `v2/src/frontend`       -- the React 19 + TS + Vite 7 application.
-#   - `v2/src/tests/frontend` -- the Vitest tree (sibling workspace member).
+#   - `v2/tests/frontend`     -- the Vitest tree (sibling workspace member).
 # A single `npm ci` at the workspace root produces one hoisted
 # `v2/node_modules` shared by both members, so the test tree resolves the
 # frontend's deps natively (one React instance, no resolver shims).
 #
 # Gates, all run after the root install:
 #   1. `npm run lint`                  -- ESLint flat config, both members.
 #   2. `npx tsc -p src/frontend`       -- app type-check (noEmit).
-#   3. `npx tsc -p src/tests/frontend` -- test-tree type-check (noEmit).
+#   3. `npx tsc -p tests/frontend`     -- test-tree type-check (noEmit).
 #   4. `npm test`                      -- vitest run (the suite under
-#                                         src/tests/frontend).
+#                                         tests/frontend).
 #
 # Mirrors `v2-typecheck.yml` (backend pyright) and `v2-backend-only-smoke.yml`
 # (backend smoke). Path-scoped so unrelated edits do not pay CI cost.
@@ -27,7 +27,7 @@ on:
       - "v2/package.json"
       - "v2/package-lock.json"
       - "v2/src/frontend/**"
-      - "v2/src/tests/frontend/**"
+      - "v2/tests/frontend/**"
       - ".github/workflows/v2-frontend-checks.yml"
   pull_request:
     branches:
@@ -36,7 +36,7 @@ on:
       - "v2/package.json"
       - "v2/package-lock.json"
       - "v2/src/frontend/**"
-      - "v2/src/tests/frontend/**"
+      - "v2/tests/frontend/**"
       - ".github/workflows/v2-frontend-checks.yml"
   workflow_dispatch:
 
@@ -67,7 +67,7 @@ jobs:
         run: npx tsc -p src/frontend
 
       - name: Typecheck tests (tsc strict, test tree)
-        run: npx tsc -p src/tests/frontend
+        run: npx tsc -p tests/frontend
 
       - name: Vitest (npm test)
         run: npm test

v2/.env.sample

@@ -46,13 +46,14 @@ AZURE_TENANT_ID=
 AZURE_UAMI_CLIENT_ID=
 
 # --- Orchestrator selection (runtime-tunable; CWYD_ namespace by design) ---
-# OrchestratorSettings.name -- "langgraph" or "agent_framework".
-# agent_framework grounds on a Foundry IQ Knowledge Base over an Azure AI
-# Search index, so it requires AZURE_INDEX_STORE=AzureSearch (cosmosdb mode).
-# pgvector deployments (AZURE_DB_TYPE=postgresql) have no such index and MUST
-# use langgraph -- selecting agent_framework there is rejected at request time
-# with HTTP 409 (ADR 0022). The local dev compose default is pgvector, so it
-# pins CWYD_ORCHESTRATOR_NAME=langgraph regardless of this value.
+# OrchestratorSettings.name -- "langgraph" or "agent_framework". Both
+# orchestrators ground on either index store and are switchable from the admin
+# UI without a redeploy. On pgvector (AZURE_DB_TYPE=postgresql) both run
+# app-side RAG over the pgvector index; on Azure AI Search (cosmosdb mode)
+# agent_framework additionally grounds on a Foundry IQ Knowledge Base over that
+# index, while langgraph runs client-side RAG. ADR 0027 supersedes the ADR 0022
+# pgvector + agent_framework block, so neither pairing is rejected. The local
+# dev compose default database is pgvector.
 CWYD_ORCHESTRATOR_NAME=agent_framework
 #
 # Foundry agent identity is NOT configured here (CU-009, ADR 0008).

v2/.gitignore

@@ -32,3 +32,6 @@ __pycache__/
 # Virtualenvs (uv default + common alternates)
 .venv/
 venv/
+
+# Frontend build artifacts (regenerated by `tsc -b` / `vite build`)
+*.tsbuildinfo

v2/docker/Dockerfile.frontend

@@ -19,7 +19,7 @@
 # every runtime + build dependency, so the dev server starts standalone with
 # zero coupling to the v2/ npm workspace or the sibling test package. The
 # workspace (v2/package.json) exists only so the Vitest tree under
-# src/tests/frontend can resolve the frontend's deps from one hoisted
+# tests/frontend can resolve the frontend's deps from one hoisted
 # node_modules; the deployable frontend never needs it.
 FROM node:20-alpine AS dev
 WORKDIR /app

v2/docs/adr/0020-frontend-tests-under-src-tests-frontend.md

@@ -1,11 +1,14 @@
 # ADR 0020 — Frontend tests live under `v2/src/tests/frontend/` (relocated from `v2/src/frontend/tests/`)
 
-- **Status**: Accepted
+> **Superseded by [ADR 0029](0029-frontend-tests-symmetric-under-tests-frontend.md) (2026-06-20).** The mirror-tree + no-colocation decision below still holds, but the test-tree root moved from `v2/src/tests/frontend/` to `v2/tests/frontend/` (symmetric with `v2/tests/backend/`). Read ADR 0029 for the current location and the build/tooling mechanics.
+
+- **Status**: Superseded by [ADR 0029](0029-frontend-tests-symmetric-under-tests-frontend.md)
 - **Date**: 2026-06-08
 - **Phase**: Post-Phase-7 (PP7 work stream — `U-PP7-RELOC`)
 - **Pillar**: Stable Core (frontend layout policy)
 - **Deciders**: CWYD v2 maintainers (repo-owner override of [ADR 0012](0012-frontend-test-folder-mirror.md) alternative #3)
 - **Supersedes**: [ADR 0012](0012-frontend-test-folder-mirror.md)
+- **Superseded by**: [ADR 0029](0029-frontend-tests-symmetric-under-tests-frontend.md) — frontend tests relocated from `v2/src/tests/frontend/` to `v2/tests/frontend/` (symmetric with the backend tree; mirror-tree + no-colocation invariants retained).
 
 ## Context
 

v2/docs/adr/0022-config-resolution-error-on-incompatible-overrides.md

@@ -1,6 +1,6 @@
 # ADR 0022 — Incompatible effective-config overrides raise a reusable `ConfigResolutionError`
 
-- **Status**: Accepted
+- **Status**: Accepted — decisions #2 (the pgvector + `agent_framework` rule) and #5 ("no silent fallback") are superseded by [ADR 0027](0027-agent-framework-app-side-rag-on-pgvector.md), which gives `agent_framework` an app-side pgvector grounding path; the reusable `ConfigResolutionError` mechanism (decisions #1 / #3 / #4) remains in force
 - **Date**: 2026-06-09
 - **Phase**: 8
 - **Pillar**: Stable Core (the `ConfigResolutionError` primitive + app-level handler) over a Configuration Layer rule (the pgvector + `agent_framework` guard)