Merge branch 'main' into alerting-v2-workflow-trigger-assign-episode

Author: adcoelho

.agents/skills/buildkite-logs/SKILL.md

@@ -105,6 +105,27 @@ spaceTest.afterAll(async ({ apiServices, scoutSpace }) => {
 
 Do not use `esArchiver` to manipulate system indices — use `kbnClient`.
 
+### Suite-wide cleanup with `globalTeardownHook`
+
+For state that's shared **across spec files** (e.g., data ingested in `global.setup.ts`, feature-flag overrides, global `uiSettings`), use the optional `globalTeardownHook` in `parallel_tests/global.teardown.ts`. It runs once after all workers finish, even if tests failed.
+
+```typescript
+import { globalTeardownHook } from '@kbn/scout-security'; // or '@kbn/scout' / '@kbn/scout-oblt'
+
+globalTeardownHook('Reset shared state', async ({ kbnClient, apiServices, log }) => {
+  // Revert global uiSettings or feature flags toggled for the whole suite
+  await kbnClient.uiSettings.unset('my:setting');
+  await apiServices.core.settings({ 'feature_flags.overrides': { 'my.flag': 'false' } });
+});
+```
+
+**Cautions:**
+
+- **`esArchiver` is intentionally not exposed** in `globalTeardownHook`. Scout's `esArchiver` only supports `loadIfNeeded` — archive unloading was never offered because it's slow and unnecessary (leftover indexes in the cluster don't break tests with idempotent `loadIfNeeded`). For state that does need resetting, use `esClient.indices.delete` / `deleteDataStream` / `deleteByQuery`.
+- **Don't load new data here** — teardown is for resetting state. Data loading belongs in `globalSetupHook`.
+- **Per-test/per-suite cleanup still belongs in `afterEach`/`afterAll`** — the global teardown is for state that other configs (running against the same Kibana/ES) would otherwise inherit.
+- Optional and opt-in by file presence: add `parallel_tests/global.teardown.ts` and you're done. `runGlobalSetup: true` already wires the project up.
+
 ## test.step() for Execution Time
 
 Each `test()` block creates a new browser context. Use `test.step()` for multi-step flows to reuse context:

.agents/skills/cypress-to-scout-migration/references/migration-best-practices.md

@@ -66,22 +66,53 @@ For **feature requests**, also probe for these common gaps (even if the field is
 - **Target user**: Who would use this — what role or persona? If not stated, ask.
 - **Dependencies**: Are there issues, features, or infrastructure changes that must land first? If so, capture them in the "Blocked By" field.
 
-## Step 7 — Show the draft and confirm
+## Step 7 — Collect and validate labels
 
-Display the complete proposed issue (title + body) and ask the user to confirm or request changes. **End your response and wait for explicit confirmation before filing.**
+Ask the user for a **team label** (e.g. `Team:Visualizations`) and any **additional labels** (e.g. `accessibility`, `performance`). Accept "none" for either. The type label (`bug` or `enhancement`) is added automatically.
 
-## Step 8 — Create the issue
+**End your response and wait for the user to reply before proceeding.**
 
-After the user confirms, create the issue:
+Once the user provides labels, validate **all of them in parallel** against the repository:
 
 ```bash
-ISSUE_BODY=$(cat <<'EOF'
+gh label list --repo elastic/kibana --search "<label>" --limit 10 --json name,description --jq '.[] | "- `\(.name)` — \(.description // "no description")"'
+```
+
+For each label:
+
+- **Exact match** → keep it.
+- **Close matches only** → show them as `` `<name>` — <description> `` and ask the user to pick one or skip.
+- **No matches** → inform the user and ask to skip or provide an alternative.
+
+If any labels need user input, **wait for the reply**, then re-validate any new labels. Repeat until all labels are resolved.
+
+## Step 8 — Show the draft and confirm
+
+Display the complete issue preview using this format:
+
+> **Title:** `<title>`
+> **Labels:** `<label1>`, `<label2>`, ...
+>
+> ---
+> \<issue body\>
+> ---
+
+Ask the user to confirm or request changes.
+
+**End your response and wait for explicit confirmation before filing.**
+
+## Step 9 — Create the issue
+
+```bash
+gh issue create --repo elastic/kibana \
+  --title "<TITLE>" \
+  --label "<label1>" --label "<label2>" --label "<labelN>" \
+  --body "$(cat <<'EOF'
 <formatted body here>
 EOF
-)
-gh issue create --repo elastic/kibana --title "<TITLE>" --body "$ISSUE_BODY" --label "<bug|enhancement>"
+)"
 ```
 
-Use label `bug` for bug reports and `enhancement` for feature requests.
+Add one `--label` flag per label.
 
-Report the new issue URL to the user when done.
+Always include the type label (`bug` or `enhancement`) plus all validated labels. Report the new issue URL to the user when done.

.agents/skills/gh-create-issue/SKILL.md

@@ -21,6 +21,7 @@ Important: Do not post GitHub comments unless explicitly stated.
 2. Neighboring Scout code in the same plugin/solution (existing specs + `test/scout/**/fixtures/**`) to spot reuse opportunities and avoid duplicating helpers.
 3. Removed/previous tests (if this is a migration) to verify behavior parity.
 4. Scout docs (open only what you need — best practices are split by test type so you can skip the irrelevant half):
+
    - **General best practices** (always relevant): `docs/extend/scout/best-practices.md`
    - **UI-only best practices** (open when reviewing UI tests): `docs/extend/scout/ui-best-practices.md`
    - **API-only best practices** (open when reviewing API tests): `docs/extend/scout/api-best-practices.md`
@@ -56,6 +57,7 @@ Open only the docs relevant to the test type(s) under review.
 - **[general]** **RBAC / realism**: minimal permissions (avoid `admin` unless required); space-aware behavior covered or explicitly out of scope.
 - **[ui]** **Flake traps**: avoid `waitForTimeout()` and time-based assertions/retries; rely on auto-waiting + explicit readiness signals. Some locators are restricted by `@kbn/eslint/scout_no_locators` (e.g. `globalLoadingIndicator`).
 - **[general]** **Cost**: avoid repeating expensive setup; consider a global setup hook for shared one-time operations.
+- **[general]** **Global teardown** (when `global.teardown.ts` is present): cleanup must use `esClient`/`kbnClient`/`apiServices`. `esArchiver` isn't on the teardown fixture surface — Scout intentionally never exposed archive-unloading (slow and unnecessary; leftover indexes don't break tests with idempotent `loadIfNeeded`). Flag teardowns that try to use `esArchiver` at all, that **load** new data (teardown is for state reset only), or that duplicate work belonging in `afterAll`/per-test cleanup.
 - **[general]** **Tags / environment**: validate deployment tags and avoid assumptions that only hold in specific environments.
 
 ### Files to skip

.agents/skills/scout-best-practices-reviewer/SKILL.md

@@ -62,6 +62,7 @@ Notes:
   - `test/<scout-root>/ui/parallel_tests/example_one.spec.ts`
   - `test/<scout-root>/ui/parallel_tests/example_two.spec.ts`
   - `test/<scout-root>/ui/parallel_tests/global.setup.ts`
+  - `test/<scout-root>/ui/parallel_tests/global.teardown.ts` is **not** generated; opt in by adding the file with a `globalTeardownHook(...)` call. See `scout-ui-testing/references/scout-ui-parallelism.md`.
 
 The generator **does not** create **`tsconfig.json`** files. Playwright runs without them, but **`node scripts/type_check`** (CI) must still include Scout specs in a TS project—see **TypeScript layout** below.
 

.agents/skills/scout-create-scaffold/SKILL.md

@@ -132,6 +132,7 @@ For general Scout API auth patterns (`requestAuth`, `samlAuth`, common headers,
 - Put shared helpers in `test/scout*/ui/fixtures/helpers.ts` (or API helpers in API fixtures).
 - Add test-subject constants in `fixtures/constants.ts` for reuse across tests and page objects.
 - For `parallel_tests/` ingestion, use `parallel_tests/global.setup.ts` + `globalSetupHook` (no `esArchiver` in spec files).
+- For suite-wide Elasticsearch/Kibana state reset (e.g. reverting feature flags or global `uiSettings`, dropping hand-indexed data that affects other Scout configs sharing the cluster), use the **optional** `globalTeardownHook` in `parallel_tests/global.teardown.ts`. Picked up automatically when `runGlobalSetup: true` — no extra config flag. Use `esClient.indices.delete` / `deleteDataStream` / `deleteByQuery`, `kbnClient.uiSettings.unset(...)`, and `apiServices.core.settings(...)` to reset state. Per-test/per-suite cleanup still belongs in `afterEach`/`afterAll`.
 
 #### Synthtrace in Scout **API** tests
 
@@ -197,6 +198,7 @@ Once the new specs typecheck and run, control returns to the parent skill. Step
 - Use `test.step(...)` inside a single `test(...)` when an FTR suite used multiple `it(...)` blocks as one journey.
 - Parallel UI: isolate per-space state via `spaceTest` + `scoutSpace`; avoid hardcoded saved object IDs and make names unique (often suffix with `scoutSpace.id`).
 - Use `globalSetupHook` in `parallel_tests/global.setup.ts` to ingest shared data once.
+- Use the optional `globalTeardownHook` in `parallel_tests/global.teardown.ts` to reset shared state once after the suite (no `esArchiver`; `esClient`/`kbnClient`/`apiServices` only). See step 6 above for the cleanup primitives and cautions.
 - Use `page.addInitScript(...)` before navigation to set localStorage/cookies (skip tours/onboarding).
 - When FTR used rison-encoded query params, replicate with `@kbn/rison` and add **`@kbn/rison`** to **`kbn_references`** on the `tsconfig.json` that includes the Scout UI files (plugin root under **Pattern A**, or `test/scout/ui/tsconfig.json` under **Pattern B**).
 - Add stable `data-test-subj` attributes when selectors are unstable.

.agents/skills/scout-migrate-from-ftr/references/execute-plan.md

@@ -53,6 +53,7 @@ description: Use when creating, updating, debugging, or reviewing Scout UI tests
 - Use `spaceTest` so you can access `scoutSpace` for worker-isolated saved objects + UI settings.
 - Pre-ingest shared ES data in `parallel_tests/global.setup.ts` via `globalSetupHook(...)`.
   - Only **worker** fixtures are available there (no `page`, `browserAuth`, `pageObjects`).
+- Reset Elasticsearch/Kibana state once after the suite via `globalTeardownHook(...)` in `parallel_tests/global.teardown.ts` (optional, opt-in by file presence). For state that does need resetting, use `esClient`/`kbnClient`/`apiServices`. See `references/scout-ui-parallelism.md`.
 - Cleanup space-scoped mutations in `afterAll` (`scoutSpace.savedObjects.cleanStandardList()`, unset UI settings you set).
 
 ## Extending fixtures

.agents/skills/scout-ui-testing/SKILL.md

@@ -14,6 +14,7 @@ Use this when working under `.../test/scout*/ui/parallel_tests/` or a `parallel.
 
 - `ui/parallel.playwright.config.ts`: `testDir: './parallel_tests'`, `workers: 2..3`, optional `runGlobalSetup: true`.
 - `ui/parallel_tests/global.setup.ts`: define `globalSetupHook(...)` (runs once total).
+- `ui/parallel_tests/global.teardown.ts` (optional): define `globalTeardownHook(...)` to reset cluster/Kibana state once after the suite. Picked up automatically when `runGlobalSetup: true`; no extra config flag.
 
 ## Minimal pattern
 
@@ -44,3 +45,38 @@ spaceTest.describe('my feature', { tag: tags.deploymentAgnostic }, () => {
 - Global setup runs once total (executed by the first worker); other workers wait for it to finish.
 - Only worker-scoped fixtures are available (for example `esArchiver`, `apiServices`, `kbnClient`, `esClient`, `log`).
 - No `page`, `browserAuth`, or `pageObjects` in `global.setup.ts`.
+
+## Global teardown hook (optional)
+
+Use `globalTeardownHook` in `parallel_tests/global.teardown.ts` to reset Kibana/cluster state **once** after all workers finish — runs even if tests failed. Same fixture surface as setup, **except `esArchiver` is intentionally not exposed**.
+
+```ts
+import { globalTeardownHook } from '@kbn/scout'; // or '@kbn/scout-oblt' / '@kbn/scout-security'
+
+globalTeardownHook('Reset shared Kibana state', async ({ esClient, kbnClient, apiServices, log }) => {
+  log.info('[teardown] resetting shared state');
+
+  // Drop hand-indexed data ingested by global.setup.ts that affects other Scout configs
+  // sharing this cluster (Scout's esArchiver intentionally has no unload — see cautions)
+  await esClient.indices.delete({ index: 'apm-8.0.0-*', ignore_unavailable: true });
+  await esClient.indices.deleteDataStream({ name: 'logs-my_dataset-*' }).catch(() => {});
+
+  // Revert any uiSettings / advanced settings the suite set globally
+  await kbnClient.uiSettings.unset('discover:searchOnPageLoad');
+  await kbnClient.uiSettings.updateGlobal({ hideAnnouncements: false });
+
+  // Revert feature-flag overrides flipped via apiServices.core.settings(...)
+  await apiServices.core.settings({ 'feature_flags.overrides': { 'discover.isEsqlDefault': 'false' } });
+
+  // Saved-object cleanup the suite created cluster-wide (per-space cleanup belongs in afterAll)
+  await kbnClient.savedObjects.cleanStandardList();
+});
+```
+
+**Cautions:**
+
+- **No `esArchiver` on the teardown surface — by design.** Scout's `esArchiver` fixture only ever exposed `loadIfNeeded`; archive-driven unloading was never supported because it's slow and adds nothing — leftover indexes in the cluster don't break tests when setup uses idempotent `loadIfNeeded`. For state that **does** need resetting, use `esClient.indices.delete` / `deleteDataStream` / `deleteByQuery` directly.
+- **Don't reload data here** — teardown is for resetting state, not for setting up new data. If you need fresh data on every run, do it in `globalSetupHook` (which is idempotent via `esArchiver.loadIfNeeded`).
+- **Per-test/per-suite cleanup still belongs in `afterEach`/`afterAll`** — the global teardown is for state shared across the whole suite (or leaked into the cluster from setup) that other configs running in the same Kibana/ES would otherwise inherit.
+- **Available fixtures**: `log`, `config`, `kbnUrl`, `esClient`, `kbnClient`, `apiServices` (plus the same lazy `samlAuth`/`isSnapshotBuild` from `coreWorkerFixtures`). No `page`/`browserAuth`/`pageObjects` and no `esArchiver`.
+- **Optional, opt-in by file presence**: just add `parallel_tests/global.teardown.ts` calling `globalTeardownHook(...)`. No new config flag — `runGlobalSetup: true` is enough.