@clipboard-health/ai-rules 2.38.3 → 2.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/ai-rules",
-  "version": "2.38.3",
+  "version": "2.39.0",
   "description": "Pre-built AI agent rules for consistent coding standards.",
   "keywords": [
     "ai",

package/skills/cb-babysit/SKILL.md

@@ -19,9 +19,9 @@ Resolve bundled "./scripts" paths relative to SKILL.md.
 
 The skill uses two sentinels with visible footer lines.
 
-**Addressed sentinel**: `<sub>🤖 <code>cb-babysit:addressed v1 core@3.17.2</code></sub>`. Appended on its own line at the end of every reply the skill posts so re-runs know which threads and review-body comments are already handled. Dedupe also recognizes the legacy `babysit-pr:addressed v1` prefix from before this skill was renamed.
+**Addressed sentinel**: `<sub>🤖 <code>cb-babysit:addressed v1 core@3.18.0</code></sub>`. Appended on its own line at the end of every reply the skill posts so re-runs know which threads and review-body comments are already handled. Dedupe also recognizes the legacy `babysit-pr:addressed v1` prefix from before this skill was renamed.
 
-**Follow-up sentinel**: `<sub>🤖 <code>cb-babysit:followup v1 core@3.17.2</code></sub>`. Attached to replies that defer an out-of-scope comment as a tracked follow-up. The sentinel is additive: the post-reply scripts still append the `addressed` sentinel at the end.
+**Follow-up sentinel**: `<sub>🤖 <code>cb-babysit:followup v1 core@3.18.0</code></sub>`. Attached to replies that defer an out-of-scope comment as a tracked follow-up. The sentinel is additive: the post-reply scripts still append the `addressed` sentinel at the end.
 
 **Sentinel recency rules.** The script emits a per-thread `activityState` with three values. Step 6a owns the handling rules for each state.
 
@@ -247,7 +247,7 @@ Body templates (the script appends the `addressed` sentinel if missing):
 - **Agree**: `Addressed in <commit-url>. <one-line what-changed>.`
 - **Disagree**: `Leaving current behavior. <reasoning>.`
 - **Already fixed**: `Already handled by <commit-url-or-file:line>. <brief pointer>.`
-- **Defer**: `Out of scope for this PR; this looks like follow-up work rather than something introduced or required by this change. <one-line rationale or pointer if useful>.\n\n<sub>🤖 <code>cb-babysit:followup v1 core@3.17.2</code></sub>`
+- **Defer**: `Out of scope for this PR; this looks like follow-up work rather than something introduced or required by this change. <one-line rationale or pointer if useful>.\n\n<sub>🤖 <code>cb-babysit:followup v1 core@3.18.0</code></sub>`
 
 For Defer replies, include the follow-up sentinel on its own line as shown. The script will append the `addressed` sentinel after it on its own line, so the final body ends with the follow-up sentinel followed by a blank line followed by the `addressed` sentinel. `grep cb-babysit:followup` finds the deferral and `grep cb-babysit:addressed` still marks the thread handled for dedupe.
 
@@ -263,7 +263,7 @@ The PR-level summary should:
 
 - Group by source. Use `## Review-body findings` for step-7 work and `## Conversation-tab comments` for step-6b work. Omit a section if its list is empty.
 - Inside each section, group verdicts under **Agree / Disagree / Already fixed / Deferred (out of scope)** subheadings. Omit a subheading if its list is empty.
-- Under **Deferred (out of scope)**, list each deferred item as a bullet, followed on its own line by `<sub>🤖 <code>cb-babysit:followup v1 core@3.17.2</code></sub>` so grep catches them individually.
+- Under **Deferred (out of scope)**, list each deferred item as a bullet, followed on its own line by `<sub>🤖 <code>cb-babysit:followup v1 core@3.18.0</code></sub>` so grep catches them individually.
 - Include the commit URL for fixes.
 - End with a fenced fingerprint block listing every current fingerprint (addressed and deferred) one per line. Include both `reviewBodyComments[].fingerprint` (whole-body, one per automated review) and `activeIssueComments[].fingerprint` (per Conversation-tab comment). Future runs dedupe by matching these against `priorBabysitSentinels`.
 

package/skills/cb-babysit/scripts/_sentinel.sh

@@ -10,7 +10,7 @@
 
 SENTINEL_PREFIX='cb-babysit:addressed v1 '
 LEGACY_SENTINEL_PREFIX='babysit-pr:addressed v1 '
-SENTINEL='<sub>🤖 <code>cb-babysit:addressed v1 core@3.17.2</code></sub>'
+SENTINEL='<sub>🤖 <code>cb-babysit:addressed v1 core@3.18.0</code></sub>'
 
 # Bot author allowlist (JSON array literal). Used by unresolvedPrComments.sh
 # as a fallback when GraphQL's `author.__typename == "Bot"` misses a GitHub

package/skills/cb-ship/references/pr-template.md

@@ -17,5 +17,5 @@ Concisely explain the user intent from session history and the meaningful behavi
 
 Optional, don't fabricate: ticket links, rollout plan, residual risk, or specific areas for reviewers to focus.
 
-<sub>🤖 <code>cb-ship:created v1 core@3.17.2</code></sub>
+<sub>🤖 <code>cb-ship:created v1 core@3.18.0</code></sub>
 ```

package/skills/flaky-critic/references/rubric.md

@@ -54,7 +54,7 @@ Opening one plan/PR per failing test when the failures share one mechanism (same
 
 **Prior-sibling signal (backtest amendment, 2026-06-11):** sibling PRs for the same mechanism that were closed _unmerged_ are a strong reject signal, not mere context. A plan citing closed-unmerged siblings must explain what is materially different this time — narrower scope alone is not an answer (the backtest's one genuine false approval cited prior wontfix siblings and explained them away).
 
-**Prior attempts (amendment, 2026-07-16):** when a fingerprint family has prior implementation tickets, the plan MUST contain a **Prior attempts** section listing each prior ticket/PR, what it blamed, what it changed, and the recurrence evidence showing its diagnosis was wrong or incomplete. A missing section is statement-missing and gets amend-and-resubmit per §1. A plan that re-proposes a mechanism a prior merged fix already tried is a substantive reject. A family with **≥2 failed merged fixes** — merged fixes followed by recurrence — is disqualified from the normal fix path: verdict = reject and escalate as needs-human. Apply the `chronic` label and hold the ticket for the deep-dive track (a dedicated dossier-first investigation stage; until it exists, chronic tickets stay held with the label for human routing). The ≥2 threshold is intentionally different from flaky-triage's ≥3-prior-implementation-tickets screen: triage counts tickets cheaply before any diagnosis exists, while the critic can see merge and recurrence outcomes and applies the sharper failed-merged-fix test. Either stage flagging chronic routes the same way; the counts are staged by the evidence available at each stage, not a contradiction.
+**Prior attempts (amendment, 2026-07-16):** when a fingerprint family has prior implementation tickets, the plan MUST contain a **Prior attempts** section listing each prior ticket/PR, what it blamed, what it changed, and the recurrence evidence showing its diagnosis was wrong or incomplete. A missing section is statement-missing and gets amend-and-resubmit per §1. A plan that re-proposes a mechanism a prior merged fix already tried is a substantive reject. A family with **≥2 failed merged fixes** — merged fixes followed by recurrence — is disqualified from the normal fix path: verdict = reject and escalate as needs-human. Apply the `chronic` label and route the family to the credential-checked, dossier-first `flaky-deep-dive` skill. The ≥2 threshold is intentionally different from flaky-triage's ≥3-prior-implementation-tickets screen: triage counts tickets cheaply before any diagnosis exists, while the critic can see merge and recurrence outcomes and applies the sharper failed-merged-fix test. Either stage flagging chronic routes the same way; the counts are staged by the evidence available at each stage, not a contradiction.
 
 ### B6 — Code fix on low-confidence diagnosis
 

package/skills/flaky-deep-dive/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: flaky-deep-dive
+description: Investigate chronic flaky-test fingerprint families with a credential-checked, dossier-first, cross-repository causal-chain method and produce a designed fix or observability design for human review. Use when flaky-triage routes a family with at least three prior implementation tickets, flaky-critic routes a family with at least two failed merged fixes, or a user asks for the chronic flake deep-dive track.
+---
+
+# Flaky Deep Dive
+
+Run a diagnosis-and-design investigation for a chronic fingerprint family. Produce a document for human review; never edit product code, create a fix branch, commit a fix, or open a fix PR.
+
+Read the bundled [Home Health dry run](references/dry-run-home-health-full-lifecycle.md) for the expected dossier and causal narrative depth. Its structure is distilled from Rocky's `hh-full-lifecycle.md` and `staging-seed-reliability.md` reference deep dives; the Phase 6 checklist remains binding where the historical artifact records an evidence limitation.
+
+## Phase 0: Enforce credential preconditions
+
+Run the preflight before reading source code or diagnosing:
+
+```bash
+bash "<flaky-deep-dive-skill-dir>/scripts/check-prerequisites.sh" "${AWS_PROFILE:-sdlc}"
+```
+
+The preflight must prove all three:
+
+1. `pup` can query Datadog APM spans and logs.
+2. The staging API is reachable through the non-production VPN.
+3. AWS read credentials are active through `aws sts get-caller-identity`.
+
+If any check fails, stop the investigation. Do not continue with reduced evidence or silently cap confidence. File a provisioning ticket linked to the chronic ticket with:
+
+- the fingerprint family and blocked investigation;
+- the failed command and exact error class;
+- the missing access: Datadog APM/log read, non-production VPN, or AWS `sdlc` read credentials;
+- the causal-chain link or fault-injection step the access blocks;
+- the remediation printed by the preflight.
+
+If the environment cannot file Linear tickets, output the exact title and body for a human to file. Do not proceed blind.
+
+For a CI-sourced E2E family, also prove access to the exact run and reporter artifact:
+
+```bash
+bash "<flaky-deep-dive-skill-dir>/../flaky-debug/scripts/fetch-llm-report.sh" \
+  "<github-actions-url>"
+```
+
+If `gh` authentication fails, run `gh auth login --hostname github.com`. If the artifact expired, rerun the source workflow or obtain the `playwright-llm-report`/Playwright HTML report. An inaccessible source artifact blocks the investigation.
+
+## Phase 1: Build the dossier first
+
+Do not diagnose until the dossier is complete.
+
+Read and follow `../flaky-debug/SKILL.md` Phase 1b in full. Its four unbounded Linear searches for the fingerprint family and exact test title are the canonical dossier recipe; do not narrow, copy, or alter them.
+
+The chronic track adds these requirements for every implementation attempt returned by that recipe:
+
+1. Read the ticket and investigation plan.
+2. Read the complete PR diff, review discussion, merge state, and fix commit through `gh`.
+3. Record what the attempt blamed and exactly what it changed.
+4. Find a later post-merge sighting that proves recurrence. Do not infer failure merely from age.
+5. Check current `main` in every repository the attempt touched.
+
+Create a `Prior attempts` table with these columns:
+
+| Prior ticket/PR/commit | What it blamed | What it changed | Recurrence evidence |
+| ---------------------- | -------------- | --------------- | ------------------- |
+
+Every prior ticket, PR, and fix commit must appear. Attempt N+1 must rule out attempts 1..N: after the table, list each prior blamed mechanism and the evidence that falsifies it, limits it to one symptom, or proves it incomplete. A new attempt that merely repeats a prior mechanism is not a deep dive.
+
+Also search open and closed-unmerged PRs labeled `flaky-test-fix`, plus recent `main` commits touching the test, helper, product surface, and implicated services. Stop and report if a current fix already covers the family.
+
+## Phase 2: Resolve ownership from the workspace
+
+Start from evidence, not the repository containing the test.
+
+Read and follow the ownership and causal-chain rules in `../flaky-debug/references/plan.md`. The chronic track additionally requires recording the registry result and checkout SHA for every implicated repository.
+
+Locate a `ClipboardHealth/groundtruth` checkout. Resolve deployed services through `registry/services.json`, then resolve repositories and owners through `registry/repos.json`:
+
+```bash
+jq --arg service "<service-id>" \
+  '.services[] | select(.id == $service)' \
+  "<groundtruth>/registry/services.json"
+
+jq --arg repo "<repo-id>" \
+  '.repos[] | select(.id == $repo)' \
+  "<groundtruth>/registry/repos.json"
+```
+
+Read `context/devin-wiki/<repo>/` when it helps locate the owning code. Follow the causal chain into every implicated repository and inspect current `main`; never stop at the repository where the test lives. Record the resolved service, repository, owner, route or responsibility, and code checkout SHA in the deliverable.
+
+If the registry is missing or cannot resolve an implicated service, treat ownership as a broken causal-chain link and design the registry/telemetry change needed to resolve it.
+
+## Phase 3: Gather evidence across every link
+
+Use all applicable evidence sources:
+
+- **LLM reporter and Playwright artifacts:** identify the exact attempt, lifecycle step, network instance, request/response body, trace ID, request ID, screenshot, and stack.
+- **Datadog APM:** follow the per-request backend-selected trace ID. Read `../flaky-debug/references/datadog-apm-traces.md` before querying.
+- **Datadog run-window logs:** query the absolute CI window for seed operations, deploys, CDC lag, queues, background jobs, and other causal events outside the request path. A trace-only search cannot establish these events.
+- **GitHub Actions:** use `gh run view`, job logs, annotations, artifacts, retry history, commit SHA, and deployed-version evidence.
+- **AWS read-only evidence:** use the active staging credentials for service-specific read commands when Datadog and CI artifacts leave an AWS-managed link unresolved.
+- **Current source:** cite file and line, config key, workflow step, or specific log event in the owning repository.
+
+Preserve exact commands, absolute time windows, trace/request IDs, run URLs, commit SHAs, and zero-result limitations in the evidence appendix.
+
+## Phase 4: Terminate the causal chain
+
+Apply the causal-chain and confidence rules in `../flaky-debug/references/plan.md` without changing their score meanings or valid terminal states.
+
+Fault-injection reproduction is mandatory for 5/5. Use a focused lower-level test or harness control that delays, fails, reorders, throttles, or disables the blamed response or step. A normal green rerun is not reproduction.
+
+When the chain is broken, do not design a speculative code fix. Convert the deliverable into the observability design that would terminate the chain on the next occurrence, including event names, fields, correlation IDs, service/repository, retention, reporter exposure, and the query that would prove or falsify the hypothesis.
+
+## Phase 5: Design the fix for review
+
+For a terminated chain, design the smallest fix at the terminal cause and name:
+
+- owning repository, files, and team;
+- behavior and contract changes;
+- migration, rollout, and compatibility constraints;
+- defensive apparatus or prior mitigations to delete after the fix;
+- fault-injection and no-retry validation;
+- residual risks and falsifying outcomes.
+
+Separate the root fix from optional resilience or observability follow-ups. Do not turn another service's defect into a local test retry. Do not implement the design.
+
+## Phase 6: Write the deliverable
+
+Write Markdown to the user-specified path, or `/tmp/flaky-deep-dive-<fingerprint>.md` by default, with:
+
+1. Title and metadata: family, repositories, status, investigator, current-main SHAs, confidence.
+2. Credential preflight evidence.
+3. `Dossier` and `Prior attempts`.
+4. Latest recurrence signatures.
+5. Causal chain with ownership resolution.
+6. Root-cause statement and discriminated alternatives.
+7. Designed fix, or `Observability design` when the chain is broken.
+8. Fault-injection reproduction and validation plan.
+9. Evidence appendix with links, commands, IDs, timestamps, and citations.
+
+End with the document path/link and a one-sentence review request. Never open a direct fix PR.

package/skills/flaky-deep-dive/references/dry-run-home-health-full-lifecycle.md

@@ -0,0 +1,177 @@
+# Dry run: Home Health `fullLifecycle.spec.ts` chronic flake
+
+- **Repo:** `cbh-admin-frontend`
+- **Spec:** `playwright/e2e/homeHealth/fullLifecycle.spec.ts`
+- **Fingerprint family:** `33deef731a10` with related variants
+- **Status:** Closed as Done at least six times before recurring
+- **Investigator:** Deep-dive track; diagnosis and design only
+- **Confidence:** 4/5; the causal chain terminates, but fault injection remains
+- **Source:** Real chronic-family deep dive completed on 2026-07-07
+- **Historical code SHA:** `fe4e2cd8424`
+- **Current-main SHA checked:** `1bafb36f8f909274b96eef840655ffdc7e15f9d0`
+
+This checked-in dry run demonstrates the expected depth and document shape. The original investigation lacked a VPN-capable environment, which correctly held confidence below 5/5. The credential-checked forward rerun below stopped before diagnosis, as the new skill requires.
+
+## 0. Credential preflight and current-main status
+
+### Credential-checked forward rerun on 2026-07-16
+
+- Datadog APM: passed a staging span query through `pup`.
+- Datadog logs: passed a staging log query through `pup`.
+- Staging VPN: failed. `curl --connect-timeout 10 --max-time 20 https://apigateway.staging.clipboardhealth.org/api/healthCheck` exited 56 with `CONNECT tunnel failed, response 403`.
+- AWS: failed. `aws sts get-caller-identity --profile sdlc` exited 255 because the `sdlc` profile was not configured.
+
+The live forward test stopped at Phase 0 and produced a provisioning-ticket body. It did not reuse the historical diagnosis as if current credentials had passed.
+
+### Current main
+
+The historical designed fix has since landed:
+
+- [PR #7574](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/7574), commit `e6818dabd950d43755c3ec96de0373062a4522ba`, hoisted the Home Health action dialogs and split the 2,096-line mega-spec.
+- [PR #7581](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/7581), commit `ed0f1e63e39e24e771b47cbe883f5925be9d45d6`, hardened the stable host and case-dialog loading path.
+- At `origin/main@1bafb36f8f909274b96eef840655ffdc7e15f9d0`, `HomeHealthDialogHost.tsx:67-77` renders the active dialog beside the list children, and `HomeHealthActiveDialog.tsx:63-81` owns every case and visit action dialog.
+
+A new investigation must stop as already fixed unless recurrence evidence post-dates those commits. The implementation matching the dry run's design is evidence that the causal document was actionable; it is not permission for this skill to open a PR.
+
+## 1. Dossier
+
+The spec was created by consolidating seven Home Health E2E files into one ten-step lifecycle test. Every later fix hardened the step where the failure last surfaced. None removed the product lifecycle churn shared by the failures.
+
+| Prior ticket/PR/commit                | What it blamed                                | What it changed                                                                                                          | Recurrence evidence                                                                                                                 |
+| ------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| STAFF-1329 / PR #6902 / `d6633c656e3` | Occurrence tab readiness                      | Added waits for occurrence tabs                                                                                          | Failure moved to visit-row lookup in STAFF-1369                                                                                     |
+| STAFF-1327 / PR #6903 / `f1bf003b6c2` | Visit-verification tab state                  | Changed product tab state and spec waits                                                                                 | Failure moved to visit-row and ROC lookup                                                                                           |
+| STAFF-1369 / PR #6915 / `3a11b8effc8` | Visit-row render race                         | Added row-lookup retries and a negotiation tweak                                                                         | Recurred as ROC visit lookup in STAFF-1495                                                                                          |
+| STAFF-1377 / PR #6930 / `07491124e72` | Remove-booked-worker assertion                | Changed the dialog and assertion                                                                                         | Later failures surfaced in other dialogs                                                                                            |
+| STAFF-1449 / PR #6987 / `53330b9c0ea` | Create transport errors                       | Added fail-fast handling and more waits                                                                                  | The family recurred; machinery grew without removing the cause                                                                      |
+| STAFF-1441 / PR #6990 / `51577fa1778` | Response-wait timing                          | Rewrote lifecycle response waits                                                                                         | STAFF-1495 recurred within days                                                                                                     |
+| STAFF-1495 / PR #7050 / `5ebd5ee839a` | ROC visit lookup                              | Hardened ROC-specific lookup                                                                                             | STAFF-1554 recurred at auth-refresh waits                                                                                           |
+| STAFF-1554 / PR #7251 / `2f942662c37` | Auth refresh during waits                     | Added a 306-line response helper tolerant of refresh                                                                     | STAFF-1582 recurred at close case                                                                                                   |
+| STAFF-1582 / PR #7316 / `28bdf114626` | Close-case flow                               | Reworked close-case steps                                                                                                | STAFF-1685 recurred with the identical title                                                                                        |
+| STAFF-1601 / PR #7321 / `b09225ddc35` | Visit-verification modal state                | Changed occurrence-table dialog behavior                                                                                 | STAFF-1673 recurred at cancel-visit dialog                                                                                          |
+| STAFF-1673 / PR #7374 / `ac7c1b79ae5` | Cancel-visit dialog open                      | Added `toPass`, immediate-failure tracking, and diagnostics                                                              | STAFF-1682 recurred six days later at close case                                                                                    |
+| STAFF-1685 / PR #7390 / `fe4e2cd8424` | Close case again                              | Added another large close-case hardening block                                                                           | STAFF-1659 and STAFF-1682 still failed                                                                                              |
+| STAFF-1789 / PR #7559 / `2b7ebc87c2d` | Backing-list refreshes while dialogs are open | Paused/canceled list observers and deferred invalidations behind `HomeHealthListRefetchGuard` with fault-injection tests | The PR documented that dialogs still lived below mapped cards; PR #7574 removed the 217-line guard and implemented the durable host |
+| STAFF-1790 / PR #7574 / `e6818dabd95` | Dialog lifecycle coupled to mapped cards      | Hoisted all desktop action dialogs and split the mega-spec                                                               | No post-merge recurrence found in the current-main recheck                                                                          |
+| PR #7581 / `ed0f1e63e39`              | Remaining host loading/history edges          | Hardened the stable host and case-dialog loading path                                                                    | No post-merge recurrence found in the current-main recheck                                                                          |
+
+### Ruled-out prior hypotheses
+
+Before the durable host in PR #7574, the next attempt had to rule out the twelve symptom fixes and the #7559 mitigation:
+
+- Readiness and locator timing are incomplete explanations because the same family migrated across tabs, rows, auth waits, and several independent dialogs after those waits landed.
+- Response-wait rewrites are incomplete because later signatures show DOM detachment after the response machinery was centralized.
+- Preserving one dialog's state is incomplete because sibling dialogs under the same list-item lifecycle continued to unmount.
+- More retries are falsified by recurrence after roughly one thousand net lines of retry and diagnostic apparatus accumulated in the spec and helpers.
+- Pausing known list refreshes was incomplete because #7559's own residual-risk statement left the dialogs below mapped cards and exposed them to ancestor updates outside those queries.
+
+### Latest recurrence signatures
+
+- STAFF-1682: the close button repeatedly became unstable and detached from the DOM during `locator.click`.
+- STAFF-1659: the cancel-visit dialog title never reached a stable visible state within 30 seconds.
+
+Both signatures point to component lifecycle churn, not a slow assertion.
+
+## 2. Causal chain
+
+**Terminal cause:** Home Health action dialogs are React descendants of query-backed list items. The dialogs' own mutations invalidate and refresh those lists. Background refreshes and status changes reconcile, reorder, or remove the list item while its dialog is open, destabilizing or unmounting the dialog subtree.
+
+```text
+Playwright click or dialog-title assertion fails
+→ the open dialog becomes unstable or disappears
+→ query invalidation/background refetch returns a new case or visit list
+→ CaseCard or VisitCard reconciles, reorders, or leaves the open list
+→ the dialog subtree, owned by that list item, remounts or unmounts
+→ terminal cause: dialog lifecycle is coupled to invalidated list-item lifecycle
+```
+
+### Ownership and historical code
+
+- `useUpdateVisit.ts:66` invalidates the case-visits query after mutations.
+- `useUpdateCase.ts:44-56` invalidates open and closed agency-case queries plus case-visits data.
+- `useCaseVisits.ts` and `useAgencyCases.ts:69` use five-minute stale and ten-minute interval refresh behavior.
+- `CaseVisits.tsx:42` sorts and maps visits on render.
+- `CaseActionsMenu.tsx:92` renders `CaseCloseDialog` inside the case card's actions.
+- `Visit/VisitActions.tsx:70` renders `CancelVisitDialog` inside the visit card's actions.
+
+Groundtruth resolves service `admin-web-app` to repository `cbh-admin-frontend`; its listed owners are Synapse, Platform, Growth, Tempo, Alchemy, and Action. The repository registry owner is Platform. No backend service is needed to terminate this particular chain.
+
+### Close-case chain
+
+1. The test opens the close dialog and clicks Close.
+2. A list invalidation or background refetch resolves while the dialog is open.
+3. The cases array changes and the owning card rerenders, producing the observed unstable element.
+4. The close mutation changes the case to closed.
+5. The open-cases query returns without that case, unmounting the card and dialog, producing the observed detached element.
+
+### Cancel-visit chain
+
+1. The test opens the cancel dialog.
+2. A prior visit mutation's invalidation resolves.
+3. The visit list resorts or reconciles.
+4. The owning visit card and its dialog remount.
+5. The title disappears before it reaches a stable asserted state.
+
+## 3. Root cause and confidence
+
+Home Health action dialogs bind their lifecycle to `CaseCard` and `VisitCard` instances produced by refetching lists. Those lists are invalidated by the dialogs' mutations and refreshed independently. A refetch during an open dialog can reconcile or remove the owning item, destroying the dialog during user interaction.
+
+This is a user-facing product race, not test-only behavior. A real administrator can lose an open dialog during background refresh; the long CI workflow merely expands the race window.
+
+Confidence is **4/5**. The render ownership, invalidation path, refresh behavior, and failure signatures establish a terminated static chain. Fault injection is still required for 5/5.
+
+## 4. Designed fix
+
+### Root fix
+
+Hoist Home Health case and visit action dialogs out of `CaseCard` and `VisitCard` into one stable dialog host mounted above the query-backed lists.
+
+- Add a `HomeHealthDialogHost` at the page or dashboard shell.
+- Make list items request `openDialog({ kind, entityId })` instead of owning modal state and rendering dialogs inline.
+- Keep one dialog instance keyed by entity ID in a subtree unaffected by list reconciliation.
+- Close only on explicit user action or mutation success.
+
+### Defense in depth
+
+While a Home Health dialog is open, pause optional focus/interval refresh churn or defer broad invalidation until the dialog closes. This reduces churn but does not replace the lifecycle fix.
+
+### Cleanup after the root fix
+
+Remove the `toPass` blocks, immediate-failure trackers, and open-dialog retry apparatus added by prior attempts once fault injection proves the stable host survives refreshes.
+
+### Test decomposition
+
+Split the ten-step mega-spec into smaller product-surface workflows with isolated seeded data, retaining one thin lifecycle smoke path if required. This reduces blast radius and gives each real mechanism a distinct fingerprint.
+
+## 5. Fault-injection reproduction
+
+1. Run the affected flow against a seeded case.
+2. Delay the close mutation while forcing the open-cases query to refetch and resolve during the click.
+3. Expect the current implementation to reproduce the detached-element signature.
+4. For cancel visit, force the case-visits refetch to resolve while the dialog is open and expect the title to disappear.
+5. Apply a prototype of the stable dialog host.
+6. Repeat both injections and prove the dialogs survive.
+7. Run the affected specs repeatedly with Playwright retries disabled.
+
+The original dry run could not execute these steps because the environment lacked staging VPN access. Under the new skill, that precondition failure requires a provisioning ticket rather than continued investigation.
+
+## 6. Observability fallback
+
+If fault injection cannot yet run after access is provisioned, add a CI-visible dialog generation counter and emit an event whenever a Home Health dialog unmounts without explicit close or mutation success. Include dialog kind, entity ID, query keys invalidated in the preceding window, and a correlation ID exposed in the Playwright reporter.
+
+The next occurrence should answer directly whether a list refetch caused the unexpected unmount.
+
+## 7. Evidence appendix
+
+- Chronic family: `33deef731a10` plus variants.
+- Consolidation: [PR #6616](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/6616), commit `afb53308a38`.
+- Latest signatures: STAFF-1682 close-case detachment and STAFF-1659 cancel-dialog invisibility.
+- Historical code checkout: `cbh-admin-frontend@fe4e2cd8424`.
+- Current-main checkout: `cbh-admin-frontend@1bafb36f8f909274b96eef840655ffdc7e15f9d0`.
+- Ownership query: `jq '.services[] | select(.repo == "cbh-admin-frontend")' groundtruth/registry/services.json`.
+- Repository query: `jq --arg repo cbh-admin-frontend '.repos[] | select(.id == $repo)' groundtruth/registry/repos.json`.
+- Current-main verification: `git log origin/main -- HomeHealthActiveDialog.tsx HomeHealthDialogHost.tsx`.
+- Key historical product areas: `CaseDashboard`, `CaseActionsMenu`, `CaseVisits`, `VisitActions`, `useUpdateCase`, `useUpdateVisit`, `useAgencyCases`, and `useCaseVisits`.
+- Prior PRs: [#6902](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/6902), [#6903](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/6903), [#6915](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/6915), [#6930](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/6930), [#6987](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/6987), [#6990](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/6990), [#7050](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/7050), [#7251](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/7251), [#7316](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/7316), [#7321](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/7321), [#7374](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/7374), [#7390](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/7390), [#7559](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/7559), [#7574](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/7574), and [#7581](https://github.com/ClipboardHealth/cbh-admin-frontend/pull/7581).
+- Historical limitation: the surviving document did not retain the exact Actions run URL, trace ID, or request ID. New `flaky-deep-dive` outputs must retain them when applicable.
+- Historical output: Rocky's `hh-full-lifecycle.md`, created 2026-07-07.

package/skills/flaky-deep-dive/scripts/check-prerequisites.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+
+set -uo pipefail
+
+AWS_PROFILE_NAME="${1:-${AWS_PROFILE:-sdlc}}"
+STAGING_HEALTH_URL="${2:-https://apigateway.staging.clipboardhealth.org/api/healthCheck}"
+
+passed=0
+failed=0
+
+print_pass() {
+  printf 'PASS: %s\n' "$1"
+  passed=$((passed + 1))
+}
+
+print_fail() {
+  printf 'FAIL: %s\n' "$1"
+  failed=$((failed + 1))
+}
+
+print_failure_details() {
+  local command_text="$1"
+  local exit_code="$2"
+  local output="$3"
+
+  printf '  Command: %s\n' "$command_text"
+  printf '  Exit: %s\n' "$exit_code"
+  if [[ -n "$output" ]]; then
+    printf '  Output:\n'
+    printf '%s\n' "$output" | sed -n '1,6p' | sed 's/^/    /'
+  fi
+}
+
+printf 'Checking flaky deep-dive prerequisites...\n'
+
+timeout_command=""
+if command -v gtimeout >/dev/null 2>&1; then
+  timeout_command="gtimeout"
+elif command -v timeout >/dev/null 2>&1; then
+  timeout_command="timeout"
+else
+  print_fail "No timeout utility is installed."
+  printf '  Remediation: install GNU coreutils so remote credential checks fail within a bounded time.\n'
+fi
+
+if ! command -v pup >/dev/null 2>&1; then
+  print_fail "pup is not installed."
+  printf '  Remediation: install pup, then authenticate with pup auth login or provide DD_API_KEY and DD_APP_KEY.\n'
+elif [[ -n "$timeout_command" ]]; then
+  trace_output="$(
+    "$timeout_command" 30 pup traces search \
+      --query='service:cbh-backend-main env:staging' \
+      --from=15m \
+      --limit=1 \
+      --read-only \
+      --no-agent \
+      --jq='.data | length' 2>&1
+  )"
+  trace_exit_code=$?
+  if [[ "$trace_exit_code" -eq 0 ]]; then
+    print_pass "Datadog APM read access works through pup."
+  else
+    print_fail "pup cannot read staging APM spans."
+    print_failure_details \
+      "pup traces search --query='service:cbh-backend-main env:staging' --from=15m --limit=1" \
+      "$trace_exit_code" \
+      "$trace_output"
+    printf '  Remediation: run pup auth login, provide DD_API_KEY and DD_APP_KEY, or request APM read access for 401/403 failures.\n'
+  fi
+
+  logs_output="$(
+    "$timeout_command" 30 pup logs search \
+      --query='service:cbh-backend-main env:staging' \
+      --from=15m \
+      --limit=1 \
+      --read-only \
+      --no-agent \
+      --jq='.data | length' 2>&1
+  )"
+  logs_exit_code=$?
+  if [[ "$logs_exit_code" -eq 0 ]]; then
+    print_pass "Datadog log read access works through pup."
+  else
+    print_fail "pup cannot read staging logs."
+    print_failure_details \
+      "pup logs search --query='service:cbh-backend-main env:staging' --from=15m --limit=1" \
+      "$logs_exit_code" \
+      "$logs_output"
+    printf '  Remediation: run pup auth login, provide DD_API_KEY and DD_APP_KEY, or request log read access for 401/403 failures.\n'
+  fi
+fi
+
+if ! command -v curl >/dev/null 2>&1; then
+  print_fail "curl is not installed."
+  printf '  Remediation: install curl and retry while connected to the non-production VPN.\n'
+else
+  staging_output="$(
+    curl \
+      --silent \
+      --show-error \
+      --write-out '\n%{http_code}' \
+      --connect-timeout 10 \
+      --max-time 20 \
+      "$STAGING_HEALTH_URL" 2>&1
+  )"
+  curl_exit_code=$?
+  staging_status="$(printf '%s\n' "$staging_output" | tail -n 1)"
+  staging_body="$(printf '%s\n' "$staging_output" | sed '$d')"
+
+  if [[ "$curl_exit_code" -eq 0 && "$staging_status" == "200" ]] &&
+    printf '%s\n' "$staging_body" | grep -Eq '"message"[[:space:]]*:[[:space:]]*"OK"'; then
+    print_pass "Staging health is reachable through the VPN (HTTP 200, message OK)."
+  else
+    print_fail "Staging health is not reachable through the VPN."
+    print_failure_details \
+      "curl --connect-timeout 10 --max-time 20 $STAGING_HEALTH_URL" \
+      "$curl_exit_code" \
+      "$staging_output"
+    printf '  Remediation: connect the Clipboard Health non-production VPN. If this environment cannot use the VPN, request a VPN-capable investigation environment.\n'
+  fi
+fi
+
+if ! command -v aws >/dev/null 2>&1; then
+  print_fail "AWS CLI is not installed."
+  printf '  Remediation: install AWS CLI v2 and configure the sdlc SSO profile.\n'
+else
+  aws_identity_output="$(
+    aws sts get-caller-identity \
+      --profile "$AWS_PROFILE_NAME" \
+      --query Account \
+      --output text \
+      --cli-connect-timeout 10 \
+      --cli-read-timeout 20 2>&1
+  )"
+  aws_identity_exit_code=$?
+
+  if [[ "$aws_identity_exit_code" -eq 0 && -n "$aws_identity_output" && "$aws_identity_output" != "None" ]]; then
+    print_pass "AWS credentials are active for profile $AWS_PROFILE_NAME (account $aws_identity_output)."
+
+    aws_read_output="$(
+      aws cloudwatch list-metrics \
+        --profile "$AWS_PROFILE_NAME" \
+        --region us-west-2 \
+        --max-items 1 \
+        --output json \
+        --cli-connect-timeout 10 \
+        --cli-read-timeout 20 2>&1
+    )"
+    aws_read_exit_code=$?
+    if [[ "$aws_read_exit_code" -eq 0 ]]; then
+      print_pass "AWS read access works for profile $AWS_PROFILE_NAME."
+    else
+      print_fail "AWS credentials lack the staging read access required by the deep-dive track."
+      print_failure_details \
+        "aws cloudwatch list-metrics --profile $AWS_PROFILE_NAME --region us-west-2 --max-items 1" \
+        "$aws_read_exit_code" \
+        "$aws_read_output"
+      printf '  Remediation: request staging read permissions, then rerun the preflight.\n'
+    fi
+  else
+    print_fail "AWS credentials are unavailable for profile $AWS_PROFILE_NAME."
+    print_failure_details \
+      "aws sts get-caller-identity --profile $AWS_PROFILE_NAME" \
+      "$aws_identity_exit_code" \
+      "$aws_identity_output"
+    printf '  Remediation: run aws sso login --profile %s. If the profile is missing, request staging read access and configure it first.\n' "$AWS_PROFILE_NAME"
+  fi
+fi
+
+printf '\nSummary: %s passed, %s failed.\n' "$passed" "$failed"
+
+if [[ "$failed" -gt 0 ]]; then
+  printf '\nDo not proceed with the deep dive. File a provisioning ticket linked to the chronic flake ticket and include the failed checks above.\n'
+  exit 1
+fi
+
+printf 'All credential preconditions are satisfied.\n'

package/skills/flaky-triage/SKILL.md

@@ -68,7 +68,7 @@ Do not merge clusters merely because failures share a run. Same-run failures can
 4. **Multi-ticket cluster** — pick the canonical (richest evidence: most failures, clearest artifacts). Comment the cluster manifest on it: member IDs, shared mechanism, evidence tier from Phase 3, and the marker `<!-- flaky-triage: cluster=<short-slug> -->`. Close the other members as Duplicate of the canonical (D2 format). Release the canonical.
 5. **Singleton or uncertain** — release as-is with a brief `<!-- flaky-triage: singleton -->` comment.
 
-Before any action above releases a canonical ticket, search Linear for the fingerprint family with the `flaky-implementation` label across all states and without a date-window restriction, then count unique prior implementation ticket IDs. At **≥3 prior implementation tickets**, do not release the canonical for normal dispatch and leave it in `Triage` unassigned. Create the Linear `chronic` label first if it does not exist. Apply the `chronic` label and hold the ticket for the deep-dive track (a dedicated dossier-first investigation stage; until it exists, chronic tickets stay held with the label for human routing). Add a ticket comment with the marker `<!-- flaky-triage: chronic -->` and dossier pointers listing every prior implementation ticket ID — but first search the ticket's existing comments for that exact marker and skip posting when it is already present; that absence check is what makes the comment idempotent across retries and re-runs. This ≥3-ticket count is a cheap screen staged before any diagnosis exists; the critic separately applies a sharper **≥2 failed merged fixes** test (see the flaky-critic rubric's Prior-attempts amendment) with the same chronic routing. The thresholds differ by design — by the evidence available at each stage — not by accident.
+Before any action above releases a canonical ticket, search Linear for the fingerprint family with the `flaky-implementation` label across all states and without a date-window restriction, then count unique prior implementation ticket IDs. At **≥3 prior implementation tickets**, do not release the canonical for normal dispatch and leave it in `Triage` unassigned. Create the Linear `chronic` label first if it does not exist. Apply the `chronic` label and route the family to the credential-checked, dossier-first `flaky-deep-dive` skill. Add a ticket comment with the marker `<!-- flaky-triage: chronic -->` and dossier pointers listing every prior implementation ticket ID — but first search the ticket's existing comments for that exact marker and skip posting when it is already present; that absence check is what makes the comment idempotent across retries and re-runs. This ≥3-ticket count is a cheap screen staged before any diagnosis exists; the critic separately applies a sharper **≥2 failed merged fixes** test (see the flaky-critic rubric's Prior-attempts amendment) with the same chronic routing. The thresholds differ by design — by the evidence available at each stage — not by accident.
 
 **Release** = set state to `Todo` and assign to the Linear API user (the viewer). Before release, ensure the ticket satisfies the Groundcrew eligibility contract from `../create-groundcrew-ticket/SKILL.md`: repository text in the description, exactly one `agent-*` label, leaf issue, and no non-terminal blockers unless intentionally blocked. Assignment + Todo is what makes groundcrew dispatch it; it also serves as the lease — released tickets never re-enter the queue.