@event4u/agent-config 5.10.0 → 6.0.0

package/.agent-src/commands/council.md

@@ -1,106 +0,0 @@
----
-model_tier: medium
-name: council
-tier: 1
-description: Council orchestrator — routes to default, pr, design, optimize, analysis, debate
-cluster: council
-type: orchestrator
-suggestion:
-  eligible: true
-  trigger_description: "external second opinion, cross-AI review, devil's advocate on a plan/roadmap/diff, council on PR/design/optimize, polling another model"
-  trigger_context: "user wants an outside critique on an artefact (roadmap, diff, prompt, files, PR, design doc, optimization target) without polluting the reviewer with the host agent's framing"
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# /council
-
-Top-level orchestrator for the `/council` family. Replaces 4 standalone
-commands with a single entry point + sub-command dispatch. Each lens
-shares the same transport, neutrality preamble, and cost gate; the
-sub-command swaps the mode-specific addendum.
-
-## Architecture — master / wrapper split
-
-`/council default` is the **master orchestrator**. It owns the full flow:
-
-1. Resolve the target + capture the original ask.
-2. Check the council is configured + price table fresh.
-3. Cost confirmation (ALWAYS ASK for billable members).
-4. Run the CLI.
-5. Render the report (5 / 5a / 5b — render → critical lens → user options).
-6. Hard floor — text only.
-
-The other three sub-commands (`pr`, `design`, `optimize`) are **wrappers**.
-Each wrapper resolves its lens-specific input (PR target, design artefact,
-optimization target + metric), captures a wrapper-specific `original_ask`,
-then delegates to `/council default` with `mode_override=<lens>`. The
-lens-specific neutrality addendums live in **one** place —
-[`scripts/ai_council/prompts.py:_MODE_TABLE`](../../scripts/ai_council/prompts.py) —
-and are selected by the `mode_override` value. Wrappers never re-implement
-cost-gate, CLI invocation, render, or the host-verdict pass; those flow
-through the master verbatim.
-
-Invariants:
-
-- Wrapper step numbers (`cost gate from /council default Step 3`,
-  `render via Step 5/5a/5b of /council default`) anchor to the master, not
-  the wrapper, so the master is the single source of truth for flow shape.
-- A new lens = a new entry in `_MODE_TABLE` + a new wrapper file that
-  follows the `pr.md` / `design.md` / `optimize.md` shape. No new master.
-- Behavioural changes to the orchestration (e.g. new render step) land in
-  `default.md` + `_MODE_TABLE`; the wrappers inherit automatically.
-
-## Sub-commands
-
-| Sub-command | Routes to | Purpose |
-|---|---|---|
-| `/council default` | `commands/council/default.md` | Generic neutral lens — prompt, roadmap, diff, or files |
-| `/council pr` | `commands/council/pr.md` | Pull a GitHub PR via `gh` and run the council on the diff with PR-specific framing |
-| `/council design` | `commands/council/design.md` | Run the council on a design doc / ADR / architecture proposal |
-| `/council optimize` | `commands/council/optimize.md` | Run the council on an optimization target — ranked, evidence-based suggestions |
-| `/council analysis` | `commands/council/analysis.md` | Run the council on a local analysis output — dedup, evidence quality, roadmap-ready Top-N |
-| `/council debate` | `commands/council/debate.md` | Multi-round debate with progressive cost disclosure — initial positions + rebuttals across N rounds |
-
-Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
-
-## Advisor mode (replace-mode personas)
-
-Any sub-command above can run in **advisor mode** by enabling one or
-more advisors in `agents/settings/.ai-council.yml` under `advisors:` (Contrarian,
-First-Principles, Expansionist, Outsider, Executor). An enabled advisor
-swaps its bound member's plain call for the same provider running the
-advisor persona — **same call count, same budget**. `council:estimate`
-surfaces every active swap on a dedicated line. Full contract: skills
-`ai-council` § "Thinking-style advisors" and
-[`docs/contracts/ai-council-config.md`](../docs/contracts/ai-council-config.md).
-
-## Dispatch
-
-1. Parse the user's argument: `/council <sub-command> [args]`.
-2. Look up the sub-command in the table above.
-3. Load the body of the routed file and follow its `## Instructions` section
-   verbatim with the remaining args.
-4. If the sub-command is unknown or missing, print the table above and ask:
-
-   > 1. default — neutral lens on a prompt / roadmap / diff / files
-   > 2. pr — review a GitHub PR (read-only by default)
-   > 3. design — review a design doc / ADR / architecture proposal
-   > 4. optimize — ranked, evidence-based optimization advice
-   > 5. analysis — critique a local analysis output (project-analyze, audits)
-   > 6. debate — multi-round rebuttals with progressive cost disclosure
-
-## Rules
-
-- **Do NOT commit, push, or open a PR** unless the sub-command explicitly
-  authorizes it. The PR sub-command can post **one** comment per
-  invocation, opt-in only.
-- **Do NOT chain sub-commands.** One `/council <sub>` per turn.
-- **Hard floor — text only.** `/council` produces text and (under
-  `pr` with explicit opt-in) one PR comment. It does NOT edit files,
-  approve / merge PRs, or run optimizations.
-- If the user invokes `/council` with no argument, **show the menu** —
-  do not guess which sub-command they meant.

package/.agent-src/commands/create-pr/description-only.md

@@ -1,159 +0,0 @@
----
-model_tier: medium
-name: create-pr:description-only
-tier: 1
-cluster: create-pr
-sub: description-only
-skills: [git-workflow]
-description: Generate a PR description as a copyable markdown block — used standalone or by create-pr
-suggestion:
-  eligible: true
-  trigger_description: "write a PR description, draft the PR text"
-  trigger_context: "PR exists or branch ready for review without description"
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# /create-pr:description-only
-
-> **Carve-out:** this command's *purpose* is the copyable preview of
-> the PR description. It therefore **ignores**
-> `verbosity.preview_artifacts` and `commands.create_pr.preview_description`
-> — both flags govern only the bare `/create-pr` flow's preview-and-
-> adjust loop. Removing the preview here would make the command a
-> no-op. Do not "fix" this; the suppression flags only apply when the
-> PR is actually being created.
-
-## Input
-
-The user may or may not provide a PR URL or branch name.
-
-## Instructions
-
-### 1. Detect PR / Branch
-
-1. If the user provides a GitHub PR URL → use that PR to get the changed files via API.
-2. If no URL → **auto-detect:**
-   - Get current branch (`git branch --show-current`).
-   - Search for an open PR on that branch via GitHub API
-     (`GET /repos/{owner}/{repo}/pulls?head={owner}:{branch}&state=open`).
-   - If exactly one PR found → use it (get files via `/pulls/{number}/files`).
-   - If no PR found → use `git diff origin/{default}..HEAD --stat` for the branch diff.
-3. **Never** reuse a PR number from earlier in the conversation.
-
-### 2. Gather context — **one parallel tool-call block**
-
-The four primary fetches below are **independent** and **must** be
-dispatched in a single parallel tool-call block, not serially. Serial
-reads here add 3+ round-trips per PR for zero benefit.
-
-```
-parallel:
-  1. Jira API           — GET /issue/{ticketId}   (skip when no ticket ID)
-  2. git diff           — git diff origin/{default}..HEAD --stat
-  3. git log            — git log origin/{default}..HEAD --format="%s"
-  4. view PR template   — .github/pull_request_template.md
-```
-
-After the block returns:
-
-- **Jira ticket**: ticket ID is extracted from the branch name
-  (e.g. `fix/DEV-4673-description` → `DEV-4673`) **before** the
-  parallel block. No ticket → skip fetch 1 silently; ask the user
-  for a number only after the block, and only if needed.
-- **PR template missing** → fall back to the structure in § 4.
-- **Read key changed files** (migrations, new classes, modified
-  services, route/config changes) — second parallel block, keyed
-  off the diff summary. Group all file reads in one block.
-- **Check roadmap/agent docs** that describe the feature intent
-  (if they exist) — fold into the second block.
-
-Anti-pattern (do **not** do this):
-
-```
-turn 1: fetch Jira
-turn 2: git diff
-turn 3: git log
-turn 4: view template
-turn 5: view file A
-turn 6: view file B
-```
-
-That's 6 round-trips for what should be 2.
-
-### 3. Build the PR title
-
-- Format: `{TICKET-ID}: {summary}` (e.g. `DEV-4673: Fix absence working time calculation`).
-- Use the Jira ticket summary if available, otherwise derive from commits.
-- If no ticket: use the most descriptive commit message or ask the user.
-
-### 4. Build the PR body
-
-**ALWAYS** use the PR template (`.github/pull_request_template.md`). Fill in its sections:
-
-- **Jira badge**: Replace `{TICKET-NUMBER}` with the actual ticket ID.
-- **Description**: Summarize the changes in 2-5 sentences. Explain *what* changed and *why*.
-  Use the Jira ticket description and commit messages as input.
-- **Type of change**: Check the appropriate checkbox(es) based on the changes.
-- **Checklist**: Leave as-is (the developer fills this in).
-- **Links**: Replace `{TICKET-NUMBER}` with the actual ticket ID.
-- **Screenshots**: Leave as `...` unless the user provides screenshots.
-
-If no PR template exists, use this structure:
-
-```markdown
-## Jira
-[{TICKET-ID}]({JIRA_BASE_URL}/browse/{TICKET-ID})
-
-## Changes
-- Bullet list of what was changed and why
-
-### Migrations
-- List new/changed migrations (if any)
-
-### Tests
-- List new/changed tests (if any)
-
-## How to test
-- Steps to verify the changes
-```
-
-### 5. Present as copyable block
-
-Show the **title** and **body** separately, each in a fenced code block so the user can copy them:
-
-```
-📋 PR Title:
-```
-{title}
-```
-
-📋 PR Body:
-```markdown
-{body}
-```
-```
-
-### 6. Ask for feedback
-
-Ask with numbered options:
-
-```
-> 1. Looks good — done
-> 2. Adjust — I'll tell you what to change
-```
-
-
-### Rules
-
-- **All output in the user's language** — but the PR body itself is in **English**.
-- **Always show the result before any further action** — never create a PR directly from this command.
-- **Always use the PR template** — read `.github/pull_request_template.md` and fill its sections. NEVER invent a custom structure.
-- **Be concise** in the description — no filler text, no restating the ticket title as a sentence.
-- **Group related changes** in the description — don't list every file, list logical changes.
-- **Mark breaking changes** clearly if the diff shows API contract changes (new/removed fields,
-  changed endpoints, changed response structure).
-- **Mention file/class names** where helpful, but don't list every single file.
-- **Highlight things reviewers should pay attention to** — complex logic, edge cases, trade-offs.

package/.agent-src/commands/create-pr.md

@@ -1,249 +0,0 @@
----
-model_tier: medium
-name: create-pr
-tier: 1
-cluster: create-pr
-skills: [git-workflow]
-description: Create a GitHub PR with structured description from Jira ticket and code changes
-suggestion:
-  eligible: true
-  trigger_description: "open a PR, create a pull request, make a PR for this branch"
-  trigger_context: "branch is ahead of base and not yet on a PR"
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# /create-pr
-
-Top-level entry point for the `/create-pr` family. Bare `/create-pr`
-runs the full create-PR flow described below. The `:description-only`
-sub-command produces a copyable PR description without creating the PR.
-
-## Sub-commands
-
-| Sub-command | Routes to | Purpose |
-|---|---|---|
-| `/create-pr` (bare) | this file (`## Default flow`) | Full flow — generate description, push, create PR |
-| `/create-pr:description-only` | `commands/create-pr/description-only.md` | Generate the PR description as a copyable markdown block, no PR creation |
-
-## Dispatch
-
-1. Parse the user's argument: `/create-pr[:<sub>] [args]`.
-2. Bare `/create-pr` → run the `## Default flow` below verbatim.
-3. `/create-pr:description-only` → load
-   `commands/create-pr/description-only.md` and follow its
-   `## Instructions` section verbatim.
-4. Unknown sub-command → print the table above and ask which one.
-
-## Default flow
-
-Uses `/create-pr:description-only` to generate the PR content, then creates the PR via GitHub API.
-
-### 1. Check prerequisites
-
-- Verify the current branch is NOT the default branch (`main` / `master`).
-- Run `git status` — warn if there are uncommitted changes.
-- Run `git log origin/{default}..HEAD --oneline` to verify there are commits to push.
-- If the branch has not been pushed yet, ask the user (in their language) whether to push.
-
-### 1b. Freshness gate — MANDATORY before opening any PR
-
-The branch may have diverged from its target base while you were
-working. A PR opened against a stale base creates merge conflicts the
-moment another PR lands first — the exact failure that motivates this
-gate.
-
-Run, in order:
-
-1. `git fetch origin {target-base} --quiet` (default: `main`).
-2. `git rev-list --count HEAD..origin/{target-base}` — number of
-   commits HEAD is **behind** the base.
-3. `gh pr list --state open --base {target-base} --limit 20 --json number,headRefName,files`
-   — open PRs targeting the same base.
-
-**Decision matrix:**
-
-| Behind | Overlapping open PR touches same files? | Action |
-|---|---|---|
-| `0` | — | Proceed to Step 2 |
-| `1–N` | No | Surface the count, ask: rebase / merge-main / proceed-anyway / cancel |
-| `1–N` | **Yes** | STOP — surface the overlapping PR number, ask: stack on top of it / wait for it to land / proceed-anyway-and-accept-conflicts / cancel |
-
-Never improvise the base or silently proceed when the branch is behind
-and overlap exists. The 10-second fetch beats hours of rebase
-reconciliation after the parent PR lands.
-
-### 2. Generate PR content
-
-Run `/create-pr:description-only` Steps 1–4 to generate the PR title and body.
-This handles: Jira ticket extraction, diff analysis, commit messages, **PR template filling**.
-
-**CRITICAL**: The PR body MUST use the project's PR template (`.github/pull_request_template.md`).
-Read the template file and fill in its sections. If the template does not exist, use the
-fallback structure defined in `/create-pr:description-only`. NEVER invent a custom body structure.
-
-**Preview gate** — read `commands.create_pr.preview_description` from
-`.agent-settings.yml` (default `false` when unset):
-
-- `false` (default): skip Steps 5–6 of `/create-pr:description-only` (the
-  copyable preview block + adjust loop). Use the generated title and body
-  directly in Step 3 below. This saves agent tokens by avoiding a full
-  re-render of the description in chat. The user can still edit the PR
-  body in the GitHub UI after creation.
-- `true`: run Steps 5–6 of `/create-pr:description-only` — present the
-  title and body as copyable blocks and ask for adjustments before
-  proceeding. The user reviews and adjusts the content in that step.
-
-### 2b. Council review — explicitly excluded
-
-`/create-pr` does **not** prompt for council review, even when
-`ai_council.enabled: true`. Invoking the PR command is an explicit
-delivery action; interrupting it with a billable opt-in question is
-out of scope.
-
-Users who want a council pass on the diff run `/council diff:<base>..<head>`
-**before** `/create-pr`. Do not re-add the prompt here without an explicit
-user request.
-
-### 3. Create the PR (draft-vs-ready, verbosity-gated)
-
-- **Head branch**: EXACT output of `git branch --show-current` from step 1.
-- **Base branch**: default branch (`main` / `master`).
-
-**Behavior change vs. legacy:** with `verbosity.routine_confirmations:
-false` (default), `/create-pr` creates the PR as draft silently. Override
-per-invocation with `:ready` / `:final` / `:draft`. Restore the prompt
-by flipping `routine_confirmations: true`. See
-[`docs/customization.md` § Verbosity](../../docs/customization.md#verbosity).
-
-Resolve `"draft"` (first match wins):
-
-1. `:ready` / `:final` arg → `false`.
-2. `:draft` arg → `true`.
-3. `routine_confirmations: true` → ask `1. draft / 2. ready`.
-4. Default → `true` (silent draft).
-
-#### 3a. Tool selection — single-call mandate
-
-```
-POST THE PR WITH ONE github-api CALL.
-NEVER COMPOSE THE BODY THROUGH SHELL, PYTHON, OR TEMP FILES.
-```
-
-Use the `github-api` tool **directly** with the markdown body in the
-JSON `data` field. The body is a regular JSON string — escaping is the
-tool's job, not yours.
-
-```
-github-api
-  method: POST
-  path:   /repos/{owner}/{repo}/pulls
-  data:   { "title": "...", "body": "<markdown>", "head": "<branch>",
-            "base": "main", "draft": <bool> }
-```
-
-**Hard prohibitions** (each one cost 3+ extra tool calls in past runs):
-
-- ❌ `python3 -c "import urllib..."` / `python3 - <<PY ... PY` heredocs
-  to serialize the body or POST it.
-- ❌ `save-file PR_BODY.md` → read back → `curl -d @PR_BODY.md`.
-- ❌ `gh pr create --body-file …` shelling out when `github-api` is
-  available in this surface.
-- ❌ Splitting `title` and `body` into two API calls (create + PATCH).
-
-The body may contain any Markdown — code fences, tables, multi-line
-HTML, emoji. Do **not** preprocess, escape, or strip newlines before
-handing it to `github-api`.
-
-If the surface genuinely lacks `github-api` (rare), fall back to
-`gh pr create --title "..." --body-file <(echo -n "<body>")` as a
-**single** shell call, never the python-urllib path.
-
-#### 3b. Submit
-
-Create the PR with the approved title/body and the resolved `draft`.
-
-**Verify after `draft: false`** — the GitHub REST API sometimes ignores
-the flag:
-
-```bash
-gh pr view {number} --json isDraft --jq '.isDraft'
-# returns true → gh pr ready {number}
-```
-
-**Silent-draft postscript** (rule 4) → see step 4b.
-
-### 4. After creation
-
-#### 4a. Strip attribution footers (mandatory)
-
-Some `github-api` tool surfaces append attribution server-side after
-the agent has sent a clean body. Per
-[`no-attribution-footers`](../rules/no-attribution-footers.md), every
-PR body must be re-checked and stripped after every write.
-
-Run this strip-pass **after PR creation and after every body PATCH**:
-
-1. Re-fetch the PR body:
-   ```
-   GET /repos/{owner}/{repo}/pulls/{number}
-   ```
-2. Search the body (case-insensitive) for any of:
-   - `Generated with [Augment Code]` / `🤖 Generated with`
-   - `Pull Request opened by [Augment Code]`
-   - `Co-authored by Augment Code`
-   - Any `augmentcode.com` link the user did not ask for
-3. **No match → done.** Skip steps 4–5; the body is already clean.
-   This is the common path and **must not** spend a verify-GET.
-4. Match found → remove the footer(s) together with surrounding
-   `---` separators and trailing whitespace, then:
-   ```
-   PATCH /repos/{owner}/{repo}/pulls/{number}
-   { "body": "<cleaned body>" }
-   ```
-   Re-fetch the body **once** to verify the strip stuck. If a
-   pattern reappears (server re-injection), repeat the PATCH once;
-   if it still reappears, surface the issue to the user and stop
-   (do not enter a strip/PATCH loop).
-5. Briefly note in the reply how many footers were removed (omit
-   the line entirely when nothing was stripped — silence is the
-   expected path, not "no footers found").
-
-#### 4b. Show the PR URL (verbosity-gated)
-
-Per `verbosity.post_action_reports` (default `minimal`):
-
-- `off` → nothing.
-- `minimal` → `→ #N opened: <url>`. Append `→ created as draft — run
-  \`gh pr ready N\` to flip` when silent-draft (rule 4); omit on ready.
-- `full` → multi-line: PR number, URL, draft state, base/head, ready-reminder.
-
-#### 4c. Jira transition (only when transitioned)
-
-Linked ticket + `routine_confirmations: true` → ask `1. Yes / 2. No`.
-Default (`false`) → skip silently. **Only emit a transition line when
-an actual Jira API call succeeded** — never announce "skipped".
-
-#### 4d. Settings short-circuit — single read per run
-
-`verbosity.routine_confirmations`, `verbosity.post_action_reports`, and
-`commands.create_pr.preview_description` are read **once** at the top
-of the run and cached for the whole `/create-pr` invocation. Do **not**
-re-read `.agent-settings.yml` in 4b / 4c — both branches resolve from
-the cached values from step 1.
-
-When all three resolve to their silent defaults (`false` / `minimal` /
-`false`), steps 4b–4c collapse to the single `→ #N opened: <url>` line
-from 4b and a silent 4c. No extra file reads, no "checking settings…"
-narration, no confirmation prompts.
-
-### Rules
-
-- **Always use the PR template** from `.github/pull_request_template.md`.
-- **Preview is opt-in** — `commands.create_pr.preview_description` (default `false`). `/create-pr:description-only` always previews.
-- **Push the branch first** if needed (with permission).
-- **No attribution footers** — see [`no-attribution-footers`](../rules/no-attribution-footers.md); strip-pass at 4a defends against tool injection.
-- Only create the PR — never merge.
-- Only commit or push with explicit permission.

package/.agent-src/commands/e2e-heal.md

@@ -1,109 +0,0 @@
----
-model_tier: medium
-name: e2e-heal
-tier: 2
-skills: [playwright-testing]
-description: Find, debug, and fix failing Playwright E2E tests
-suggestion:
-  eligible: true
-  trigger_description: "fix the failing E2E tests, playwright tests are red"
-  trigger_context: "failing test output from tests/e2e/"
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# e2e-heal
-
-> **Mobile scope:** this command targets Playwright (browser/web) tests only. For Detox / Maestro / Appium / XCUITest / Espresso failures, use the `mobile-e2e-strategy` skill plus the framework's own diagnostic tooling — the Playwright-specific steps below do not apply to native mobile.
-
-## Instructions
-
-### 1. Identify failing tests
-
-- Ask the user:
-
-> 1. Run all E2E tests and fix whatever fails
-> 2. Fix a specific test file — which one?
-> 3. Fix tests that failed in CI — provide the CI run URL or error output
-
-- Read the Playwright guideline: `../docs/guidelines/e2e/playwright.md`
-
-### 2. Run failing tests
-
-- Execute the test(s) to see current errors:
-  ```bash
-  npx playwright test [file] --reporter=list 2>&1 | tail -30
-  ```
-- If all tests pass → report success and stop.
-- List all failing tests with their error messages.
-
-### 3. Debug each failure (one at a time)
-
-For each failing test:
-
-1. **Read the error** — understand what's expected vs. actual.
-2. **Classify the failure**:
-
-| Type | Symptom | Action |
-|---|---|---|
-| Selector changed | Element not found | Update locator (prefer semantic) |
-| Timing issue | Timeout | Add proper waits or `waitForResponse` |
-| Assertion mismatch | Expected ≠ Actual | Update expected value or test logic |
-| App bug | Test is correct, app is broken | Mark `test.fixme()` |
-| Data dependency | Missing test data | Fix seed/setup |
-| Environment issue | Works locally, fails in CI | Check config, viewport, baseURL |
-
-3. **Fix the test** — make the smallest change that resolves the issue.
-4. **Verify** — re-run only the fixed test:
-   ```bash
-   npx playwright test [file] -g "test name"
-   ```
-5. **If it passes** → move to next failure.
-6. **If it still fails** → try one more approach. After 3 failed attempts on the same test, mark as `test.fixme()`.
-
-### 4. Handle unfixable tests
-
-If a test fails because the **application** is broken (not the test):
-
-```ts
-test.fixme('should display avatar', async ({ page }) => {
-  // BUG: Avatar endpoint returns 404 since API v2 migration.
-  // TODO: Remove fixme when GALA-XXXX is resolved.
-  await page.goto('/profile')
-  await expect(page.getByRole('img', { name: 'Avatar' })).toBeVisible()
-})
-```
-
-- Always add a comment explaining current vs. expected behavior.
-- Ask the user if a bug ticket should be created.
-
-### 5. Final verification
-
-- Run all tests once more to confirm everything passes (or is properly marked `fixme`):
-  ```bash
-  npx playwright test --reporter=list
-  ```
-- Report results to the user.
-
-### 6. Summary
-
-Present a table:
-
-```
-| # | Test | Status | Action |
-|---|---|---|---|
-| 1 | login.spec.ts > should login | ✅ Fixed | Updated email locator |
-| 2 | checkout.spec.ts > should pay | ✅ Fixed | Added waitForResponse |
-| 3 | profile.spec.ts > should show avatar | ⚠️ fixme | App bug — avatar 404 |
-```
-
-### Rules
-
-- **Fix one test at a time** — don't batch fixes.
-- **Max 3 attempts per test** — then mark `test.fixme()` and move on.
-- **Never use `waitForTimeout()`** as a fix — always find the proper wait condition.
-- **Prefer updating locators** over adding retries.
-- **Do NOT commit or push** unless the user asks.
-- **Do NOT delete failing tests** — fix them or mark as `fixme`.