@clipboard-health/ai-rules 2.41.2 → 2.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/ai-rules",
-  "version": "2.41.2",
+  "version": "2.43.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.20.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.
+**Addressed sentinel**: `<sub>🤖 <code>cb-babysit:addressed v1 core@3.22.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.20.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.
+**Follow-up sentinel**: `<sub>🤖 <code>cb-babysit:followup v1 core@3.22.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.20.0</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.22.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.20.0</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.22.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.20.0</code></sub>'
+SENTINEL='<sub>🤖 <code>cb-babysit:addressed v1 core@3.22.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/SKILL.md

@@ -28,22 +28,22 @@ Resolve bundled "./references" paths relative to SKILL.md.
 7. Output:
 
    ```plaintext
-   - PR: [Complete url] (e.g., `https://github.com/clipboardhealth/core-utils/pull/123`)
-
    [One concise sentence describing what was implemented and shipped.]
 
    [Optional bullets for the most important user-facing outcomes. Omit when the sentence is sufficient.]
 
-   Additional information:
+   Details:
 
    - Directory: [Absolute path]
    - Branch: [Branch name]
    - Review: [N findings — M applied, K dismissed with a one-line reason each] (omit if step 4 skipped or found nothing)
    - Session: [Resume command from 6a] (omit if none)
    - Existing changes: [Uncommitted changes that remain outside the shipped scope] (omit if none)
+
+   🚀 [Complete url] (e.g., `https://github.com/clipboardhealth/core-utils/pull/123`) 🚀
    ```
 
-   Keep the PR as the first bullet and visually separate it from everything
-   else with a blank line. Use the middle section only for meaningful behavior
-   or outcome details. Put lower-priority handoff metadata and caveats under
-   `Additional information`.
+   Keep the PR as the final line and visually separate it from everything else
+   with a blank line. Use the middle section only for meaningful behavior or
+   outcome details. Put lower-priority handoff metadata and caveats under
+   `Details`.

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.20.0</code></sub>
+<sub>🤖 <code>cb-ship:created v1 core@3.22.0</code></sub>
 ```

package/skills/flaky-closeout/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: flaky-closeout
+description: Sweep the flaky-test pipeline after fixes merge by closing out the root-cause KB, closing clearly superseded tickets as Done under D3, and re-dispatching critic-rejected plans for amendment. Use for the recurring flaky close-out task, a post-merge flaky-fix sweep, or a dry-run/backtest of close-out decisions.
+---
+
+<!-- cspell:ignore backtest backtesting groundcrew redispatch worktree -->
+
+# Flaky Closeout
+
+Run three post-merge sweeps in one read-first, write-later pass. This stage
+maintains the pipeline's learning and dispatch loops; it does not diagnose new
+root causes or implement product fixes.
+
+Read these files before deciding or writing:
+
+- `../flaky-debug/references/fix.md` for the KB close-out contract.
+- `../flaky-debug/references/root-cause-kb/README.md` and every plausible KB
+  entry.
+- `../flaky-critic/SKILL.md` and its rubric for D3, marker, and second-reject
+  semantics.
+- `../create-groundcrew-ticket/SKILL.md` for dispatch eligibility.
+- `../blind-backtest/SKILL.md` when running `--backtest`.
+- [Comment templates](./references/comment-templates.md) before posting.
+
+## Invariants
+
+- Never cancel a ticket. Cancel authority remains human-only.
+- Close a superseded ticket as **Done**, not Canceled or Duplicate. Done enters
+  the 21-day verifying window so the recurrence loop can reopen a false
+  supersession.
+- Require a clear mechanism match before D3 closure: the same KB entry or
+  causal mechanism **and** the same failure-signature class.
+- Decide the complete action ledger before any external write.
+- Search existing comments for the exact marker before every write. A marker is
+  a lease for that action, not a substitute for checking current state.
+- Batch all KB changes from one run into one focused `core-utils` PR. Never
+  commit directly to the default branch and never auto-merge.
+- Do not schedule or re-arm this skill. When invoked by a recurring task, follow
+  re-arm instructions from the task description only after the digest.
+
+## Modes and window
+
+Support these modes:
+
+- **Production:** perform reads, build the ledger, then write.
+- **`--dry-run`:** perform every read and decision, but make no Linear, GitHub,
+  git, or repository write. Print the exact proposed comments, state changes,
+  and KB diff plan. Represent the unavailable KB PR URL as
+  `<future KB PR for run <run-key>>`.
+- **`--backtest`:** imply `--dry-run` and follow `../blind-backtest/SKILL.md`.
+  Freeze the requested historical cutoff and keep judgments isolated from the
+  answer key. If separate assembler and judge contexts are unavailable, stop
+  and report that the blind protocol cannot be satisfied.
+
+Before the first production run for a new rule revision, run a backtest and a
+current dry run as separate invocations. Do not promote from historical results
+alone.
+
+Use an explicit `--since` value or the last successful-run timestamp supplied
+by the recurring task, subtracting three days for overlap. If neither exists,
+look back 21 days. Accept `--bounce-age-days`; default to 3. Print the effective
+window, overlap, cutoff, and bounce age in the digest.
+
+## Phase 1: Build the source manifest
+
+Start these independent discovery reads concurrently:
+
+- primary merged-PR search;
+- missing-label Linear fallback;
+- non-terminal flaky-ticket universe;
+- bounced-ticket queue.
+
+After discovery, deduplicate ticket IDs and fetch each full issue and comment set
+once. Cache the records for the entire run.
+
+### Merged-fix manifest
+
+Search merged PRs across the `ClipboardHealth` organization:
+
+1. Primary source: every merged PR carrying `flaky-test-fix` in the effective
+   window. Paginate; do not trust a single result page.
+2. Label-hygiene fallback: recent `flaky-implementation` and chronic deep-dive
+   tickets whose linked PR merged in the window and demonstrably fixed a flaky
+   mechanism, even when the PR omitted the label. Require the PR body or Linear
+   attachment to identify the source ticket. Record a missing-label digest
+   risk; do not mutate PR labels.
+3. Exclude closed-unmerged PRs. Deduplicate by repository and PR number.
+
+Build a cheap first-pass PR record:
+
+- repository, PR URL, merge timestamp, merge commit, title, and labels;
+- source Linear ticket ID from the PR body or attachment;
+- cached source ticket ID and related-ticket IDs.
+
+Hydrate changed files, diff, detailed validation evidence, and full related
+tickets only after a pending KB close-out or plausible D3 join makes the PR
+actionable. From the hydrated records, extract `KB match:`, pending
+`Knowledge-base close-out`, causal mechanism, signature class, validation
+evidence, and every flake sighting timestamp.
+
+If a PR lacks a source ticket ID, report it as unresolved and take no close-out
+action for it.
+
+### Bounce manifest
+
+List `flaky-implementation` tickets in Triage. Fetch each issue and all comments;
+list results truncate descriptions.
+
+Keep a ticket only when it has:
+
+- a critic marker with `mode=enforce` and `verdict=reject`; current markers also
+  carry `disposition=amend-and-resubmit` or
+  `disposition=substantive-reject`, while legacy markers may omit disposition;
+- a verdict older than the bounce-age threshold;
+- no later plan amendment that addresses the verdict;
+- no completed close-out re-dispatch for that verdict.
+
+Use the verdict comment ID when available; otherwise use its timestamp. A later
+issue edit is only a possible amendment: read the current plan and confirm that
+it addresses each cited rule before skipping re-dispatch.
+
+Treat `verdict=needs-human disposition=second-reject` as terminal
+`needs-human`. Also classify two enforce-mode rejects separated by a plan
+amendment as `needs-human` when processing older marker formats. Never
+re-dispatch either case; include it in the digest for Rocky.
+
+A re-dispatch marker on a ticket that is still Groundcrew-ineligible means
+`eligibility mutation pending`, not `skip`. Resume only the missing eligibility
+changes; do not post the comment again.
+
+Phase 1 is complete only when every manifest item has full ticket descriptions
+and comments. Do not decide against truncated list results.
+
+## Phase 2: Sweep KB close-outs
+
+Inspect both the source ticket and related or superseded implementation tickets.
+A pending close-out can live on a different fingerprint family than the PR that
+fixed its mechanism.
+
+For every pending close-out:
+
+1. Confirm the target PR merged. If not, leave it pending and report it.
+2. Resolve the plan's `KB match:` to an existing entry. If the plan says none,
+   create a new entry only when the evidenced causal terminus is genuinely new.
+3. Compare the plan, merged diff, validation, and related recurrence. Prepare
+   the required dry-run statement from `flaky-debug/references/fix.md`.
+4. Record:
+   - the recurrence or variant addressed;
+   - the landed fix and PR;
+   - any newly established partial or failed-scope lesson;
+   - affected repository/surface, evidence, current status, and `Last reviewed`;
+   - symptom-index changes only when the new signature is more discriminating.
+5. Deduplicate updates by KB entry and mechanism. One PR can close several
+   tickets; one KB entry should receive one coherent edit.
+
+Use this completed-action marker only after the focused KB PR exists:
+
+```html
+<!-- flaky-closeout: kb-done pr=<full-core-utils-pr-url> -->
+```
+
+After the action ledger is complete, sort each KB action as
+`<entry-path>|<source-PR>|<affected-ticket-IDs>` and hash the resulting list.
+Derive the run key from the recurring task's scheduled occurrence ID or exact
+UTC cutoff timestamp plus the first 12 characters of that ledger hash. Use
+deterministic branch `flaky-closeout/<run-key>` and put this marker in the PR
+body:
+
+```html
+<!-- flaky-closeout: kb-run=<run-key> ledger=<full-hash> -->
+```
+
+Before creating a branch or PR, search that exact head branch. Reuse an open or
+merged PR only when its trusted PR-body marker has the same run key and full
+ledger hash. A different ledger always gets a different run key, even on the
+same day. This verified PR lookup is the idempotency key when a prior run
+created the KB PR but failed before commenting on every ticket.
+
+In production, create a fresh `core-utils` worktree on that branch, apply every
+recorded KB edit, run `node --run sync-ai-rules` and `node --run verify` with the
+repository Node version, and ship one PR through the repository's
+`cb-work`/`cb-ship` workflow. Link the PR in a close-out comment on every
+affected ticket. If the PR cannot be created, do not post the marker; report
+the failure and leave the close-out retryable. If the PR exists, reuse it and
+retry only missing ticket comments.
+
+## Phase 3: Sweep supersessions under D3
+
+From the Phase 1 cache, build indexes over every non-terminal ticket labeled
+`flaky-investigation` or `flaky-implementation`: normalized KB entry, causal
+mechanism, signature class, source PR, and fingerprint family. Join every
+merged fix against those indexes. Do not limit the join to the source
+fingerprint family and do not repeat the organization-wide ticket scan per PR.
+
+Use the KB mechanism as the cross-family join key:
+
+1. Resolve each candidate's `KB match:` line. If it has no line, require
+   equivalent explicit causal evidence in its plan; text similarity alone is
+   insufficient.
+2. Confirm the merged PR fixes the same causal locus, not merely a nearby
+   symptom.
+3. Confirm the signature class matches, such as provider-topology remount,
+   query-row overlay teardown, Cognito alias lookup, or CDC readiness.
+4. Parse the candidate's earliest relevant sighting timestamp and prove it is
+   earlier than the PR merge timestamp. If no reliable sighting time exists, do
+   not close.
+5. Check that the ticket has no post-merge recurrence for that mechanism.
+
+Classify the candidate:
+
+- **Clear match:** stage the D3 comment from
+  [comment templates](./references/comment-templates.md), then set the ticket to
+  Done. Include the PR, mechanism, sighting and merge timestamps, 21-day
+  verifying window, and recurrence-loop reopen safety net.
+- **Ambiguous:** stage one possible-supersession comment tagging Rocky and leave
+  state unchanged.
+- **No match:** take no action.
+
+Markers:
+
+```html
+<!-- flaky-closeout: superseded-by=<full-source-pr-url> -->
+<!-- flaky-closeout: possible-supersession pr=<full-source-pr-url> -->
+```
+
+Post the clear-match comment before setting Done. If the state update fails,
+retain the comment marker and retry only the missing state change on the next
+run. A supersession marker on a still-open ticket therefore means
+`state-change pending`, not `skip`. Never change a ticket to Canceled.
+
+## Phase 4: Sweep bounced plans
+
+For each eligible first-bounce ticket:
+
+1. Quote the decisive critic verdict and rule IDs.
+2. State the exact plan amendment required; do not propose the implementation
+   fix yourself.
+3. Validate every field against the eligibility contract in
+   `../create-groundcrew-ticket/SKILL.md`.
+4. Post the re-plan instruction with the verdict-specific marker, then make only
+   the state, assignee, and label changes required to restore eligibility. Do
+   not rewrite repository, parent, or blocker semantics.
+
+Do not re-dispatch when a later plan already addresses the verdict, the same
+verdict marker exists, or this is the second bounce. Leave second bounces in
+Triage and list them as `needs-human`.
+
+## Phase 5: Execute and verify
+
+In production, execute the already-decided ledger in this order:
+
+1. Create the single KB PR and add KB close-out comments.
+2. Post D3 or possible-supersession comments and apply D3 state changes.
+3. Post bounce instructions and restore Groundcrew eligibility.
+
+Execute each ticket's ordered mutation bundle, then refetch it once. Verify only
+the marker, state, assignee, labels, relations, and linked PR fields that bundle
+could change. Preserve individual mutation failures in the ledger so the next
+run can reconcile marker versus state. Continue independent actions after one
+failure, but never claim a failed action succeeded.
+
+In dry-run or backtest, print the same ordered ledger with exact comment bodies
+and state mutations, prefixed `WOULD`; write nothing.
+
+## Phase 6: Digest
+
+End with:
+
+- effective window, mode, merged PR count, source-ticket resolution count, and
+  missing-label fallbacks;
+- KB entries and tickets updated, pending, skipped by marker, and KB PR URL;
+- D3 closed, possible supersessions, no-match candidates, and state failures;
+- bounce candidates, re-dispatched, already amended, marker-skipped, and
+  needs-human;
+- every ambiguity, missing timestamp, missing ticket ID, incomplete evidence,
+  or failed write.
+
+When backtesting, use the blind-backtest output contract. See the checked-in
+[2026-07-17 acceptance report](./references/acceptance-report-2026-07-17.md).
+It records a targeted historical check, not a reusable backtest fixture or
+approval for future live rule revisions.

package/skills/flaky-closeout/references/acceptance-report-2026-07-17.md

@@ -0,0 +1,110 @@
+<!-- cspell:ignore backtest -->
+
+# 2026-07-17 Acceptance Report
+
+This is a targeted, write-free acceptance check for the handoff examples. It is
+not a promotion-grade blind backtest, a reusable test fixture, or a replacement
+for live shadow agreement.
+
+## Cohort and cutoff
+
+- Window: `2026-06-26T00:00:00Z` through `2026-07-17T14:30:00Z`.
+- Primary PR scan: 31 merged `flaky-test-fix` PRs: 23 in
+  `cbh-admin-frontend`, five in `cbh-mobile-app`, and three in
+  `clipboard-health`.
+- Source-ticket resolution: 30 of 31 primary PRs carry a `STAFF-*` ID in the
+  title or body. `clipboard-health#26528` is unresolved and therefore produces
+  no action.
+- Merged fix: `ClipboardHealth/cbh-admin-frontend#7608`, merged
+  `2026-07-17T13:08:25Z`, source ticket `STAFF-1846`.
+- Supersession candidate: `STAFF-1856`, sighting
+  `2026-07-16T14:30:36Z`.
+- Bounce cohort: `STAFF-1860`, `STAFF-1862`, `STAFF-1868`, `STAFF-1873`, and
+  `STAFF-1874`; critic verdicts were posted around `2026-07-17T12:09Z`.
+- Bounce evaluation time: `2026-07-17T14:30:00Z` with
+  `--bounce-age-days=0`. This override tests verdict detection and routing;
+  production retains the three-day default so later amendments can suppress
+  re-dispatch.
+
+The decision pass uses ticket plans, verdict text, PR body and diff metadata,
+merge time, and sighting time. Human close-out outcomes are used only in the
+result comparison.
+
+The KB contract landed at the end of this window. A full-description Linear
+search for `KB close-out` found two implementation plans: `STAFF-1856`, whose
+mechanism was fixed by merged #7608, and `STAFF-1874`, whose proposed fix had
+not merged and therefore remains pending. The bounce scan found the five named
+Triage tickets below.
+
+## Proposed dry-run actions
+
+### KB close-out
+
+`STAFF-1856` contains a pending close-out for
+`query-driven-list-dialog-teardown.md`. PR #7608 fixes the provider-topology
+variant that remounted the authenticated route above the open Home Health menu.
+
+Expected update:
+
+- Add the provider-topology recurrence as another replaceable-ancestor surface.
+- Record #7608 and its delayed or immediate-token regression coverage.
+- Record that the dialog-only hoist in #7574 was correctly scoped but could not
+  prevent a remount from a higher provider boundary.
+- Link the resulting focused `core-utils` KB PR from `STAFF-1856` and
+  `STAFF-1846`.
+
+### D3 supersession
+
+Would close `STAFF-1856` as Done under D3:
+
+- same terminal cause: token-dependent `KnockProviderWrapper` topology switch
+  remounts the authenticated route;
+- same signature class: an already-resolved menu item detaches before its user
+  action starts;
+- sighting `2026-07-16T14:30:36Z` predates merge
+  `2026-07-17T13:08:25Z`;
+- #7608 changed the same composition files named by the plan and added the
+  requested token-resolution regression.
+
+The PR lacked the `flaky-test-fix` label, so it is admitted only through the
+linked flaky deep-dive ticket fallback and reported as a label-hygiene risk.
+
+### Bounce re-dispatch
+
+Would re-dispatch each first bounce to Todo for plan amendment:
+
+| Ticket     | Verdict gap to carry into the re-plan instruction                                         |
+| ---------- | ----------------------------------------------------------------------------------------- |
+| STAFF-1860 | C1 requires same-identity reconciliation after ambiguous 504, fresh identity on collision |
+| STAFF-1862 | A3 plan must state fake-timer restoration in `afterEach`                                  |
+| STAFF-1868 | B1 forbids token-minting refresh retries without non-amplifying control                   |
+| STAFF-1873 | B1/B6/B8 require no uncapped 429 retry and a terminated causal chain                      |
+| STAFF-1874 | B1/B6/B8 require no uncapped 429 retry and a terminated owning-service cause              |
+
+No ticket had a prior closeout re-dispatch marker or a second critic rejection
+at the frozen cutoff. Their critic comments use the legacy
+`verdict=reject mode=enforce` marker without a disposition field; the bounce
+scan accepts that enforce-only shape while still excluding shadow markers.
+
+## Outcome comparison
+
+- **D3:** match. Rocky's `STAFF-1856` close-out cited #7608, the exact mechanism,
+  the pre-merge sighting, Done, the 21-day verifying window, and recurrence
+  reopen behavior.
+- **KB:** match. The human close-out explicitly transferred the
+  provider-topology recurrence, #7608, and the dialog-only-hoist scope lesson to
+  the KB close-out.
+- **Bounces:** all five verdicts are detected with the required amendment
+  content. This report evaluates routing, not whether the later planner
+  produced an acceptable amendment.
+
+## Limitations
+
+- The cohort was selected from named handoff examples and is not balanced.
+- The #7608 missing-label fallback is necessary for this case but needs live
+  monitoring for false inclusion.
+- The acceptance check does not grade ambiguous supersession precision,
+  second-bounce handling, KB edit quality across multiple entries, or live
+  tool/write idempotency.
+- Before production scheduling, run a larger blind backtest and a live
+  write-free shadow pass.

package/skills/flaky-closeout/references/comment-templates.md

@@ -0,0 +1,58 @@
+<!-- cspell:ignore redispatch -->
+
+# Flaky Closeout Comment Templates
+
+Fill every placeholder from fetched evidence. Do not post a state-changing
+template with an unknown timestamp, mechanism, or PR. A possible-supersession
+comment may use its explicit missing-timestamp statement because it leaves state
+unchanged.
+
+## KB close-out
+
+```markdown
+<Use the canonical final close-out statement from
+flaky-debug/references/fix.md verbatim.>
+
+<!-- flaky-closeout: kb-done pr=<KB PR URL> -->
+```
+
+## Clear D3 supersession
+
+```markdown
+Already fixed (D3): covered by merged PR <source PR URL> from <source ticket>.
+It fixes the same mechanism: <mechanism and causal locus>. This ticket's
+<signature class> sighting at <sighting timestamp> predates the merge at
+<merge timestamp>.
+
+Closing Done: the family enters the 21-day verifying window. If this mechanism
+flakes again, the recurrence loop reopens the ticket with its history.
+
+<!-- flaky-closeout: superseded-by=<source PR URL> -->
+```
+
+## Possible supersession
+
+```markdown
+@Rocky Warren possible supersession: merged PR <source PR URL> may cover this
+ticket through <shared mechanism>, but <specific ambiguity> prevents a D3
+closure. The relevant sighting is <timestamp or missing-timestamp statement>.
+Please confirm the mechanism match; state is unchanged.
+
+<!-- flaky-closeout: possible-supersession pr=<source PR URL> -->
+```
+
+## Bounce re-dispatch
+
+```markdown
+Re-dispatching for plan amendment after the critic verdict at <verdict link or
+timestamp>.
+
+Required amendment:
+
+- <rule ID>: <specific missing or contradicted plan statement>
+
+Amend the plan against the verdict, preserve the existing investigation
+evidence, and resubmit it to the critic before implementation.
+
+<!-- flaky-closeout: bounce-redispatch verdict=<comment ID or timestamp> -->
+```

package/skills/flaky-triage/SKILL.md

@@ -1,31 +1,35 @@
 ---
 name: flaky-triage
-description: Scheduled triage stage between flake-intake and agent dispatch. Clusters flaky-investigation tickets by shared root cause, closes duplicates and infra blips, and releases one canonical ticket per cluster for dispatch. Use when running the recurring flaky-triage task, when asked to triage the flaky queue, or to backtest clustering against historical tickets.
+description: Scheduled triage stage between flake-intake and agent dispatch. Clusters flaky-investigation tickets by shared root cause, closes duplicates and infra blips, and releases one repository-owned canonical ticket per cluster for dispatch. Use when running the recurring flaky-triage task, when asked to triage the flaky queue, or to backtest clustering against historical tickets.
 ---
 
-The pipeline stage between flake-intake (deterministic, string-level collapse: bursts and storms) and per-ticket dispatch. Intake creates investigation tickets in the **Triage** state, where groundcrew ignores them. This skill clusters them semantically — same root cause, even when error text differs — then performs ticket surgery and releases exactly one dispatchable ticket per root cause.
+<!-- cspell:words backtest backtesting deflake dispatchable groundcrew -->
 
-This skill routes; it never diagnoses. Do not propose fixes, read test source files, or run flaky-debug. Diagnosis happens later, on the released ticket, through the normal dispatch flow.
+The pipeline stage between flake-intake (deterministic, string-level collapse: bursts and storms) and per-ticket dispatch. Intake creates investigation tickets in the **Triage** state, where groundcrew ignores them. This skill clusters them semantically — same root cause, even when error text differs — then performs ticket surgery and releases exactly one dispatchable ticket per root cause and implementation repository.
+
+This skill routes and classifies known mechanisms from existing ticket evidence; it never performs a new source-level diagnosis. Do not propose fixes, read test source files, or run flaky-debug. Diagnosis happens later, on the released ticket, through the normal dispatch flow.
 
 ## Rules
 
-- One canonical ticket per root cause, never one per sighting (rubric B5).
+- One repository-owned canonical ticket per root cause, never one per sighting within an implementation repository (rubric B5).
+- One implementation ticket per mechanism cluster per repository. A cross-repo mechanism match coordinates repository-owned fixes; it never consolidates them across repositories.
 - Never hold a ticket hostage: anything you cannot confidently cluster is released as a singleton. The worst case must equal the no-triage baseline.
 - Load `../flaky-critic/references/rubric.md` before citing close-out rules. Cite rubric rule IDs (B5, D1, D2, D3) in every close-out comment.
 - Decide the full cluster picture before writing anything to Linear.
 - Keep bulky data in local scratch files; keep only the manifest and decisions in context.
-- All Linear writes are idempotent: skip any action whose marker comment already exists.
+- All Linear writes are idempotent. Use exact markers only to deduplicate comments. Immediately before state, label, relation, or marker-comment writes, re-read the current value and skip only when the desired state, label, relation, or exact marker already exists.
+- Production Linear writes are single-flight. The recurring task or caller must serialize the entire Phase 4 write pass; if exclusive execution cannot be established, remain in dry-run and report the blocker. After an API conflict, re-fetch the affected tickets and retry only actions that are still missing.
 
 **Rubric IDs** (cite the matching ID in every close-out comment):
 
-- **B5** — one canonical ticket per root cause, never one per sighting.
+- **B5** — one repository-owned canonical ticket per root cause, never one per sighting within an implementation repository.
 - **D1** — infra/environment incident: cancel with incident window + correlation evidence + why no code fix applies + re-arm note.
 - **D2** — duplicate of canonical: matching evidence + no new implementation ticket needed beyond the canonical.
 - **D3** — already-fixed: matches an investigation/implementation ticket closed in the last 14 days.
 
 ## Phase 1: Queue
 
-Fetch candidate tickets from Linear: project `Groundcrew`, label `flaky-investigation`, state `Triage`. (During migration, also include state `Todo` with no assignee.) Skip tickets that already carry a `<!-- flaky-triage:` marker comment. If the queue is empty, skip to the digest.
+Fetch candidate tickets from Linear: project `Groundcrew`, label `flaky-investigation`, state `Triage`. (During migration, also include state `Todo` with no assignee.) A marker is not enough to skip a ticket: verify that its promised disposition is reflected in the issue state and relations. If a marked ticket remains in the queue, treat it as a partial action, reconstruct the intended disposition, skip completed writes, and resume the rest. If the queue is empty, skip to the digest.
 
 Use `list_issues` only to enumerate the queue; fetch each candidate with `get_issue` — list results truncate descriptions and will silently drop the Flake details JSON. Fetch candidate details in parallel when the available tooling supports it.
 
@@ -37,7 +41,7 @@ Phase 1 is done when every non-skipped candidate has a manifest row — don't ca
 
 Fetch what is already being worked, to catch duplicates before they spawn plans. Scope searches to the repos, files, normalized errors, helper names, and prior tickets from the Phase 1 manifest first; widen only when the scoped search leaves a plausible duplicate unresolved.
 
-- Open Linear tickets labeled `flaky-implementation` (any state but terminal).
+- Open Linear tickets labeled `flaky-implementation` (any state but terminal). Collect plausible IDs first, then fetch each with `get_issue` and read its comments in parallel when the available tooling supports it; list results truncate the plan, `KB match:` statement, critic approval, and PR context needed for mechanism coordination.
 - PRs: search `flaky-test-fix` in both `open` and `closed` states; treat closed-unmerged siblings as duplicate signals, not already-fixed proof. Also try title keywords `flaky`/`deflake`.
 - Open `[storm:` / `[burst:` tickets and their contained fingerprints.
 - Investigation/implementation tickets closed in the last 14 days, for already-fixed matches only after confirming the merged fix is on main and the sighting predates it (D3).
@@ -60,22 +64,59 @@ Cluster by strongest shared evidence first:
 
 Do not merge clusters merely because failures share a run. Same-run failures can have different root causes.
 
-## Phase 4: Act (per cluster, in this order)
+### Knowledge-base mechanism coordination
+
+Finish the root-cause clusters above before this second pass. Same-repo duplicate decisions take precedence; knowledge-base coordination must not rescue a duplicate or split one root cause into several tickets. Before the lookup, use the Phase 4 rules and chronic threshold to plan every disposition without writing to Linear.
+
+For every canonical that the plan would release, plus every plausibly related in-flight implementation ticket from Phase 2:
+
+1. Open `../flaky-debug/references/root-cause-kb/README.md` once. Compare every member's failure signature, failure surface, and available causal evidence with the symptom index, collect the union of plausible entries, then read each unique entry once in full, including **What failed and why**.
+2. For each matched entry, widen the Phase 2 in-flight search across repositories using the entry link, entry title, and mechanism terms. Fetch every non-terminal `flaky-implementation` match before deciding the mechanism cluster.
+3. Record one of the exact `KB match:` statements defined in `../flaky-debug/SKILL.md` Phase 1b, including the failed fixes to avoid when an entry matches. Perform the lookup at triage time; do not trust a copied or stale plan line.
+4. Group tickets only when the evidence matches the same KB entry and mechanism. A shared symptom without the entry's mechanism is insufficient. Record the entry link, mechanism, ticket IDs, repositories, and whether each member is a provisional canonical or in-flight implementation.
+
+A mechanism cluster exists when at least two surviving provisional canonicals in the run, or one surviving provisional canonical plus an in-flight implementation ticket, match the same entry. The members may represent different fingerprint families. Do not merge members from different repositories, close one as a duplicate of the other, or create a cross-repo canonical. Each repository keeps its own implementation ticket.
+
+When several members are in the same repository, apply the existing root-cause and D2 rules first so at most one canonical per mechanism and repository remains. A KB match alone is not D2 evidence; if the root-cause evidence does not support deduplication, keep the tickets independent and record the ambiguity as a risk instead of forcing them into one mechanism cluster. `KB match: none` cannot establish a production mechanism cluster. Record a likely shared mechanism with no matching entry as a KB gap in risks and in dry-run/backtest output; it does not block either ticket's normal release.
+
+## Phase 4: Plan, coordinate, then act
+
+First, choose exactly one intended disposition per cluster using the ordered rules below. Record the actions without writing to Linear.
 
-1. **Matches in-flight work** — error family or mechanism matches an open implementation ticket or open PR: close every member as Duplicate linked to that canonical, comment citing B5/D2 with the match evidence. Release nothing.
-2. **Matches an open storm/burst ticket** — normalized error matches its signature or contained fingerprints: close members as Duplicate of the storm/burst ticket so late stragglers join the existing event.
-3. **Infra blip / environment incident** — an incident cluster (evidence tier 7): use the Phase 3 threshold above. In production runs, corroborate via Phase 2 (Datadog monitor history / error spike through `pup` when available; passed-on-retry signals). Default action: close all members as Canceled with a D1 comment. If the incident exposes a hardening gap (e.g., seed path lacks diagnostics), release ONE canonical for that hardening and dup the rest to it — never one per helper.
-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.
+1. **Matches in-flight work** — within the same repository, the error family or root cause matches an open implementation ticket or open PR: plan to close every member as Duplicate linked to that canonical and comment citing B5/D2 with the match evidence. Plan no release. A shared KB mechanism alone is not D2 evidence, especially across repositories; handle it through mechanism coordination below.
+2. **Matches an open storm/burst ticket** — normalized error matches its signature or contained fingerprints: plan to close members as Duplicate of the storm/burst ticket so late stragglers join the existing event.
+3. **Infra blip / environment incident** — an incident cluster (evidence tier 7): use the Phase 3 threshold above. In production runs, corroborate via Phase 2 (Datadog monitor history / error spike through `pup` when available; passed-on-retry signals). Default disposition: plan to close all members as Canceled with a D1 comment. If the incident exposes a hardening gap (e.g., seed path lacks diagnostics), plan to release ONE canonical for that hardening and dup the rest to it — never one per helper.
+4. **Same-repository multi-ticket cluster** — within each implementation repository, pick the canonical (richest evidence: most failures, clearest artifacts). Plan to comment the cluster manifest on it: member IDs, shared mechanism, evidence tier from Phase 3, and the marker `<!-- flaky-triage: cluster=<short-slug> -->`. Plan to close only the same-repository members as Duplicate of the canonical (D2 format) and release the canonical. When a non-incident root cause spans repositories, retain one repository-owned canonical per repository and coordinate them as mechanism-cluster peers; never close one repository's ticket as a duplicate of another repository's canonical.
+5. **Singleton or uncertain** — plan to 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 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.
+After every cluster has an intended disposition, apply the chronic screen described below and act on each knowledge-base mechanism cluster. Finish both gates for the entire run before executing any planned release, cancellation, or duplicate action:
+
+1. Add pairwise Linear `relatedTo` links between all members. Do not add `blockedBy` or `blocks` relations; repository fixes may proceed in parallel.
+2. Post a scope-boundary comment on every member. List all peer tickets and repositories, state which repository this ticket owns, and strike any `sibling-repo` step that would create a mirror ticket in a repository owned by a peer. Name the most advanced member as the reference implementation when one has an in-flight PR or a plan with a flaky-critic approval marker. Rank an in-flight PR ahead of an approved plan; if members are equally advanced, tell each to reference the peer plans for mechanism consistency.
+3. End each comment with the stable marker `<!-- flaky-triage: mechanism-cluster=<entry-slug> members=<sorted-ticket-ids> -->`. Fetch every member's relations and comments in parallel before writing, then skip each link or comment whose relation or exact marker already exists.
+
+Use this comment shape, substituting the member-specific scope and reference:
+
+```text
+Mechanism coordination: STAFF-X and STAFF-Y match KB mechanism <entry>.
+
+Scope: STAFF-X owns <repo-a>. Skip this ticket's sibling-repo step that would create a mirror ticket in <repo-b>; STAFF-Y owns that repository. Reference <ticket/plan/PR> for mechanism consistency. The fixes may proceed in parallel; do not add a blocked-by relation.
+
+<!-- flaky-triage: mechanism-cluster=<entry-slug> members=STAFF-X,STAFF-Y -->
+```
+
+For every planned canonical release, 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**, remove the planned normal release and leave the canonical 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.
 
+Only after the chronic and mechanism-coordination gates finish for the entire run, execute the remaining planned dispositions. Preserve the order within each disposition: post its evidence or scope comment and relation first, then change state or release it. Re-read immediately before each write and, after any conflict, resume only the actions still missing.
+
 ## Phase 5: Digest
 
-End with a compact report: queue size, cluster count with members and evidence tiers, released / duplicated / canceled / chronic-held counts, in-flight matches found, chronic detections with each canonical ticket and its prior implementation ticket IDs, and risks (possible false merges, missing evidence). When run as a recurring task, follow any re-arm instructions in the task description after the digest.
+End with a compact report: queue size, cluster count with members and evidence tiers, released / duplicated / canceled / chronic-held counts, in-flight matches found, chronic detections with each canonical ticket and its prior implementation ticket IDs, and risks (possible false merges, missing evidence, KB gaps). Add a dedicated line in this shape: `mechanism clusters: N — <entry>: STAFF-X (<repo-a>), STAFF-Y (<repo-b>); ...`, or `mechanism clusters: 0`. When run as a recurring task, follow any re-arm instructions in the task description after the digest.
 
 ## Dry-run and backtest
 
-When invoked with `--dry-run`, when the task description says dry run, or when backtesting: perform Phases 1–4 fully but **write nothing to Linear** — print each proposed action (`close STAFF-X as Duplicate of STAFF-Y, evidence: …`) instead. For a backtest, run blind against the historical tickets you are given (do not look up how they were actually resolved until after stating your clusters), then output only your proposed clusters and actions.
+When invoked with `--dry-run`, when the task description says dry run, or when backtesting: perform Phases 1–4 fully but **write nothing to Linear**. Print each proposed close/release action, chronic-label creation or application, each `relatedTo` link, the exact scope-boundary comment for every mechanism-cluster member, and the mechanism-cluster digest line. Print likely mechanism clusters that lack a shared KB entry as `KB gap` findings, including their members and repositories, but do not count them as production mechanism clusters. For grading, also render the candidate `relatedTo` links and scope-boundary comments that the missing entry prevents, clearly prefixed `not production-eligible: KB gap`.
+
+For a backtest, run blind against the historical tickets you are given. Use only content that existed before the coordination decision; do not read later ticket states, PR outcomes, relations, or human coordination comments until after stating the proposed clusters and actions. Join the result to the human action afterward and report whether member selection, repository ownership, mirror-step removal, and reference-implementation choice agree.