canary-test-cli 7.2.0 → 8.0.0

package/agents/skills/README.md

@@ -13,8 +13,9 @@ it), see [Guides](../../docs/guides/index.md).
 
 ```text
 agents/skills/
-├── claude-code/                    # Claude Code skills (21)
+├── claude-code/                    # Claude Code skills (24)
 │   ├── canary-add-framework/
+│   ├── canary-batwoman/
 │   ├── canary-blackhawk/
 │   ├── canary-cassandra/
 │   ├── canary-ci-ready/
@@ -30,9 +31,11 @@ agents/skills/
 │   ├── canary-pr-guardian/
 │   ├── canary-promote-test/
 │   ├── canary-savant/
+│   ├── canary-screech/
 │   ├── canary-setup-harness/
 │   ├── canary-shadow/
 │   ├── canary-ship/
+│   ├── canary-strix/
 │   ├── canary-test-pipeline/
 │   └── canary-test-reporter/
 └── README.md                       # this file
@@ -90,6 +93,21 @@ slash-command entry points.
   into a Markdown and/or JSON report with pass/fail/flaky/skipped counts.
   Complements `canary-fail-fast` (which aborts early) by summarising the full
   run at the end.
+- [`canary-screech`](./claude-code/canary-screech/SKILL.md) — Bundled executable
+  skill (`scripts/cli.mjs`). Broken-main siren: reads the cross-run history
+  store, decides whether the default branch is red, and emits a one-page blast
+  (culprit commit range, failure cluster, owning area, quarantine-or-revert
+  recommendation, chat-ready block) as a markdown artifact plus a `::error`
+  annotation. The cross-run complement to the two above — neither of them can
+  tell that the branch itself went red.
+
+### Closure auditing
+
+- [`canary-batwoman`](./claude-code/canary-batwoman/SKILL.md) — Reports whether
+  the files a closed issue's fix changed have actually **executed** since that
+  fix merged. GitHub closes an issue on a keyword match, which checks neither
+  that the fix works nor that it ever ran. Advisory, and the only skill here
+  that requires the network (`gh`): deterministic, network, no agent.
 
 ### Test hygiene & reliability
 
@@ -204,9 +222,10 @@ Use the canary-generate-test skill to write a load test for /v1/search.
 Most skills here are documentation, not executable artifacts — they describe
 _how an agent should behave_, not a function to call. Several are bundled
 executable skills with their own CLI entry point (`cli:` in frontmatter).
-`canary-fail-fast`, `canary-katana`, and `canary-blackhawk` ship a Node entry
-(`scripts/cli.mjs`); `canary-instrument` and `canary-test-reporter` ship a
-Python entry (`scripts/cli.py`). Run those directly, e.g.:
+`canary-fail-fast`, `canary-katana`, `canary-screech`, and `canary-blackhawk`
+ship a Node entry (`scripts/cli.mjs`); `canary-instrument` and
+`canary-test-reporter` ship a Python entry (`scripts/cli.py`). Run those
+directly, e.g.:
 
 ```bash
 node agents/skills/claude-code/canary-fail-fast/scripts/cli.mjs --help

package/agents/skills/claude-code/canary-batwoman/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: canary-batwoman
+description:
+  Closure auditing — reports whether the files a closed issue's fix changed have
+  actually EXECUTED since that fix merged. GitHub closes an issue on a keyword
+  match in a PR body, which checks neither that the fix works nor that it ever
+  ran; batwoman answers only the second question, per changed file, and names
+  the files it could not answer for. Use when the user asks "did that fix
+  actually run", "is this issue really done", "audit a closed issue", or after a
+  batch of merges. Advisory and read-only — it never asserts correctness, never
+  fails a job, and never reopens an issue. NOT a test runner, NOT a coverage
+  tool (a dormant workflow has whatever coverage it always had), and NOT a
+  correctness check.
+cli: canary batwoman
+requires: [node>=20, gh]
+---
+
+# Canary Batwoman
+
+GitHub closes an issue when a merged PR body matches `Closes #N`. That is a
+**string match with no denominator**: nothing checks that the fix works, and
+nothing checks that the fix ever ran. The issue moves to `CLOSED` on the
+strength of a keyword.
+
+Batwoman audits the claim. For each file the closing PR changed, it reports
+whether that artifact has executed since the merge — and, just as importantly,
+which files it could not decide about.
+
+## The founding case
+
+canary#749 fixed a false-green in `.github/workflows/refresh-arch-baseline.yml`.
+It merged as `1e0c05b` and auto-closed on the keyword. Verified afterwards:
+
+- 11 script unit tests passed
+- 97 static workflow assertions passed
+- the workflow itself **had not run since twelve days before the fix merged** —
+  it is label-triggered, so it stayed dormant until someone applied the label
+
+Every gate the repo owns read that as done. The fix was real and well-tested;
+its end-to-end path was unproven. **Verified and exercised are different
+properties**, and that gap is what batwoman makes visible.
+
+## Usage
+
+```bash
+canary batwoman --help
+```
+
+That one needs no credentials, no network and no fixtures. A real audit needs
+the repository named and `gh` authenticated:
+
+```bash
+export GITHUB_REPOSITORY=owner/name   # never inferred from a git remote
+canary batwoman --issue 749           # the report
+canary batwoman --issue 749 --json    # the machine shape, for CI
+```
+
+`GITHUB_REPOSITORY` is required rather than guessed. Auditing the wrong
+repository's run history would produce a confident answer about the wrong thing,
+which is worse than refusing.
+
+## What the five statuses mean
+
+| status           | meaning                                                                    |
+| ---------------- | -------------------------------------------------------------------------- |
+| `exercised`      | a run started after the merge, and it names which                          |
+| `not-exercised`  | the artifact has not run since — with the `on:` trigger explaining why     |
+| `abstain`        | a probe looked and could not tell (unreadable history, untraceable script) |
+| `no-probe`       | nothing looked: a registry gap, fixable by adding a probe                  |
+| `not-applicable` | prose, config, or a file this change deleted                               |
+
+`abstain` and `no-probe` are deliberately separate, and neither is folded into
+anything resembling a pass. **The summary always prints all five counts**, and
+they always sum to the changed-file total — a report over a subset presented as
+a report over the whole is the exact defect batwoman exists to detect.
+
+There is no `assessed` field, no score, and no success token anywhere in the
+output. A convenient `passed: true` in the JSON is the field a CI wrapper would
+grow later; it does not exist, and a test asserts it stays that way.
+
+## What it will not tell you
+
+- **Whether the fix is correct.** Batwoman proves execution, never behaviour. A
+  workflow that ran and did the wrong thing reports `exercised`.
+- **Whether coverage is adequate.** A dormant workflow has whatever coverage it
+  always had; that is the point.
+- **Anything about a file it has no probe for.** `ts/src/**` is an honest
+  `no-probe` row in v1, countable rather than silent.
+
+## Probes shipped
+
+| probe             | matches                   | decides by                                                               |
+| ----------------- | ------------------------- | ------------------------------------------------------------------------ |
+| `workflow`        | `.github/workflows/*.yml` | a run created after the merge; reads `on:` to explain a dormant one      |
+| `workflow-script` | `scripts/*.mjs`           | the workflows that name it, inheriting `exercised` if **any** caller ran |
+| `no-execution`    | `*.md`, config manifests  | returns `not-applicable`, reading nothing                                |
+
+A script nothing references **abstains** rather than reporting as never-run: "no
+workflow calls this" is a statement about the repo, not about the script, which
+may still be run by a hand or a hook.
+
+## Requires the network, and says so
+
+Batwoman shells out to `gh` for run history and for the closing PR. That is a
+property, not a tier — unlike the deterministic offline detectors alongside it
+(`canary-savant`, `canary-blackhawk`, `canary-cassandra`, `canary-katana`),
+which run anywhere node does.
+
+An unauthenticated or missing `gh` does not degrade to a clean report. It fails
+loudly, and every affected file becomes an `abstain` naming the failure. Per
+this repo's standing rule, **cannot-verify is a finding, not a skip**.
+
+## In CI
+
+`.github/workflows/batwoman.yml` runs it on every push to `main`, deriving the
+issue from the merge commit's closing keyword — the very keyword match batwoman
+questions, which is the right input precisely because it is what GitHub acted
+on. Advisory: every step is `continue-on-error`, and a merge that closes nothing
+is reported and skipped rather than passing silently over an empty set.

package/agents/skills/claude-code/canary-cassandra/SKILL.md

@@ -3,14 +3,15 @@ name: canary-cassandra
 description: >
   Vacuous-test detection — finds tests that PASS WITHOUT PROVING ANYTHING: an
   assertion that compares a value with itself, a test that never invokes the
-  target it claims to cover, and a test whose every assertion is an absence
-  observed on a bystander rather than on the code under test. Use when the user
-  says "why did this pass against the bug", "are these tests actually testing
-  anything", "audit my suite for vacuous tests", "green but worthless", or after
-  a bug shipped through a green suite. Advisory and deterministic — no LLM, no
-  execution. NOT for tests with zero assertions (that is `canary review-test`'s
-  LINT-006), NOT for flaky tests (canary-flake-hunter), and NOT a coverage tool
-  — a vacuous test has coverage, which is exactly why coverage never caught it.
+  target it claims to cover, and a test whose every assertion is an absence, or
+  a trivially true presence check, observed on a bystander rather than on the
+  code under test. Use when the user says "why did this pass against the bug",
+  "are these tests actually testing anything", "audit my suite for vacuous
+  tests", "green but worthless", or after a bug shipped through a green suite.
+  Advisory and deterministic — no LLM, no execution. NOT for tests with zero
+  assertions (that is `canary review-test`'s LINT-006), NOT for flaky tests
+  (canary-flake-hunter), and NOT a coverage tool — a vacuous test has coverage,
+  which is exactly why coverage never caught it.
 cli: scripts/cli.mjs
 requires: [node>=20]
 ---
@@ -29,15 +30,20 @@ Cassandra is Tier-0: deterministic, no LLM, no network, no execution.
 
 ## What it finds
 
-| Rule      | Severity | Fires on                                                                                                          |
-| --------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
-| `VAC-001` | critical | An assertion whose expectation is identical to the value it checks — `expect(true).toBe(true)`, `assert x == x`   |
-| `VAC-002` | warning  | The test never references the target it claims to cover                                                           |
-| `VAC-003` | warning  | Every assertion in the test asserts an _absence_, and none of them observes the target — so nothing proves it ran |
+| Rule      | Severity | Fires on                                                                                                                                                          |
+| --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `VAC-001` | critical | An assertion whose expectation is identical to the value it checks — `expect(true).toBe(true)`, `assert x == x`                                                   |
+| `VAC-002` | warning  | The test never references the target it claims to cover                                                                                                           |
+| `VAC-003` | warning  | Every assertion in the test asserts an _absence_, and none of them observes the target — so nothing proves it ran                                                 |
+| `VAC-005` | warning  | Every assertion is a trivially true _presence_ check (`toBeDefined`, `toBeTruthy`, `assert x is not None`) on a value the test built itself before the target ran |
 
 `VAC-001` is deterministic, hence `critical`: no implementation can fail it.
-`VAC-002` and `VAC-003` depend on resolving a target, which is inference, so
-they are `warning` and carry a fidelity tier.
+`VAC-005` abstains (no finding) whenever it cannot prove the subject is a
+bystander, such as a name bound in a hook or a multi-line initialiser. `VAC-004`
+is reserved for the self-excusing-skip rule
+(`docs/changes/vac-004-self-excusing-skip/`). `VAC-002` and `VAC-003` depend on
+resolving a target, which is inference, so they are `warning` and carry a
+fidelity tier.
 
 ## Run it
 
@@ -45,7 +51,8 @@ Two doors, one detector. Both run the same engine rules, so they cannot disagree
 about a finding or about the denominator.
 
 ```bash
-canary vacuity-check tests/            # human-readable
+canary vacuity-check tests/            # human-readable, skips counted per reason
+canary vacuity-check tests/ --verbose  # ...plus every skipped test at file:line
 canary vacuity-check tests/ --json     # verdict + denominator + skips
 canary vacuity-check tests/a.test.ts   # one file
 ```

package/agents/skills/claude-code/canary-cassandra/scripts/cli.mjs

@@ -4,7 +4,8 @@
 // Finds tests that PASS WITHOUT PROVING ANYTHING: an assertion that compares a
 // value with itself (VAC-001), a test that never invokes the target it claims
 // to cover (VAC-002), and a test whose every assertion is an absence observed
-// on a bystander (VAC-003).
+// on a bystander (VAC-003), and a test whose every assertion is a trivially
+// true presence check on a value the test built itself (VAC-005).
 //
 //   <paths>    files or directories to scan (default: the current directory).
 //   --json     emit machine-readable findings instead of human text.
@@ -53,6 +54,7 @@ const USAGE =
   '  VAC-001 (critical)  assertion compares a value with itself\n' +
   '  VAC-002 (warning)   the test never invokes the target it covers\n' +
   '  VAC-003 (warning)   every assertion is an absence, on a bystander\n' +
+  '  VAC-005 (warning)   every assertion is trivial presence, on a bystander\n' +
   '\n' +
   'The denominator is TESTS read, not files. A zero denominator exits 3 under\n' +
   '--strict; it is never reported as a clean scan.';

package/agents/skills/claude-code/canary-ci-ready/SKILL.md

@@ -14,6 +14,14 @@ Analyses a test suite across five dimensions and produces a readiness score. Use
 this before promoting a suite to CI, or as the convergence gate in
 `/canary-test-pipeline`.
 
+**Deterministic scorer:** run `canary ci-ready [--root <dir>] [--json]` first.
+It scores every check that has a real input and reports `skip`, naming the
+missing input, for every check that does not. A skip is never a pass. Today only
+flakiness has a producer behind it, so expect the other four to skip until
+their inputs exist. The verdict is `ready` (all five passed), `incomplete`
+(nothing failed, something skipped), `not-ready` (exit 1) or `abstained`
+(nothing scored, exit 3).
+
 ## When to Use
 
 - Before wiring a new test suite into CI for the first time
@@ -30,8 +38,9 @@ Run all five checks and score each pass / warn / fail.
 
 ### 1. Coverage depth
 
-Read `.canary/test-inventory.json` if present. If absent or older than 7 days,
-run `canary coverage` to generate fresh data.
+Read `.canary/test-inventory.json` if present. Nothing in canary produces this
+file yet (there is no `canary coverage` command), so when it is absent this
+check is a `skip`, not a pass or a fail.
 
 Default threshold: depth ≥ 2 for all endpoints in critical areas. Override with
 `--threshold <n>`.
@@ -47,6 +56,11 @@ Default threshold: depth ≥ 2 for all endpoints in critical areas. Override wit
 Read `test-results/quarantine-ledger.json` (or the path in
 `.canary/company.json` under `quarantine_ledger_path` if set).
 
+No tool writes a quarantine ledger yet, so `canary ci-ready` scores flakiness
+from the run-history store instead: the last 30 runs in
+`test-results/reports/history-v2.jsonl`. Any test flaking in 10% or more of its
+runs fails the check, any lower flake rate warns, and no flakes passes.
+
 A quarantined test is acceptable only when it has a linked open issue (Jira or
 GitHub). Check issue state:
 
@@ -83,7 +97,10 @@ Cross-reference the top 5 risk-scored areas from `critical-areas.json` against
 
 ### 5. Suite runtime
 
-Read `test-results/run-history.ndjson`. Use the p95 of the last 10 runs.
+Run history lives in `test-results/reports/history-v2.jsonl`. The store does not
+record run or test durations today, so there is no p95 to compute and
+`canary ci-ready` reports this check as `skip`. The scoring below applies once
+durations are recorded.
 
 **With harness MCP available:** score the p95 against trend history rather than
 an absolute clock. Call `get_perf_baselines` and compare this run's p95 to the

package/agents/skills/claude-code/canary-fleet-health/SKILL.md

@@ -75,6 +75,7 @@ of the full digest — cheaper and more focused:
 | --------------------------------------- | -------------------------------------------------------------------- |
 | Flaky tests fleet-wide                  | `canary analyze flaky --window-runs 30 --min-rate-pct 10 --json`     |
 | Failure spikes                          | `canary analyze spikes --delta-pp 20 --json`                         |
+| CI-run flakes (reruns to green)         | `canary analyze gh-flaky --repo <owner/name> --json`                 |
 | Cross-suite common failures             | `canary analyze common-failures --min-suites 2 --json`               |
 | Newly broken tests after a green streak | `canary analyze regression-candidates --json`                        |
 | "Area health" / degrading areas         | See the caveat below — this dimension does not currently return data |

package/agents/skills/claude-code/canary-pr-guardian/SKILL.md

@@ -58,6 +58,21 @@ canary guardian pr-check --format json
 
 Findings are `untested-new-code` gaps. If there are none, report clean and stop.
 
+**Coverage regressions (#606).** `--coverage` alone answers only "is this
+changed unit covered at all?". To also catch a unit whose coverage _fell_
+against the base branch, pass the base ref's report as well:
+
+```bash
+canary guardian pr-check --coverage lcov.info --base-coverage base-lcov.info --format json
+```
+
+That adds `coverage-regression` findings, graded by how many percentage points
+were lost. Most CI never uploads a base-branch artifact; without
+`--base-coverage` the run degrades **loudly** to "delta unavailable — head-only"
+and `coverage_delta.status` reports `unavailable`. Read that field before
+treating an empty finding list as "no regressions" — a run that compared nothing
+has abstained, not passed.
+
 ### Phase 1 — Quality audit (Tier ≥ 1, read-only)
 
 Export the availability signal so the probe reports the ceiling, then audit the

package/agents/skills/claude-code/canary-screech/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: canary-screech
+description:
+  Broken-main siren. Reads the cross-run history store, decides whether the
+  default branch is red, and emits a one-page blast — culprit commit range,
+  failure cluster, owning area, a quarantine-or-revert recommendation, and a
+  chat-ready block — as a standalone markdown artifact plus a GitHub Actions
+  `::error` annotation. Self-contained; emits only, never posts.
+cli: scripts/cli.mjs
+requires: [node>=20]
+---
+
+# Canary Screech
+
+The **cross-run, branch-level** member of the failure-surfacing family:
+
+| Skill                  | Scope                   | Knows the branch went red? |
+| ---------------------- | ----------------------- | -------------------------- |
+| `canary-fail-fast`     | in-run; aborts early    | no                         |
+| `canary-test-reporter` | per-run summary         | no                         |
+| **`canary-screech`**   | cross-run, branch-level | **yes**                    |
+
+"The default branch is red" is not a fact any single run holds. It lives in the
+sequence of runs, which is why this skill reads the run-history store rather
+than a results file.
+
+## Signal source
+
+`test-results/reports/history-v2.jsonl` — the run-history store, one `RunRecord`
+JSON object per line. No network, no credentials, no service, and no write
+access to anything except the `--out` artifact path. A GH Actions webhook and a
+polling loop were both considered and rejected: this family's contract is
+deterministic and self-contained, and the store already carries `branch`,
+`commit_sha`, `timestamp`, the pass/fail counts, and per-test `area` and
+`failure_category`.
+
+## What it emits
+
+1. A standalone **markdown one-pager** (`--out`) with five sections: culprit
+   commit range, failure cluster, owning area, recommendation, chat-ready block.
+2. A single GitHub Actions **`::error` annotation**, so the break shows in the
+   Checks UI rather than only in a file.
+
+It emits the chat block. It does not post it — there is no Slack, Teams, or
+webhook integration, by design.
+
+## Recommendation
+
+| Verdict       | When                                                                  |
+| ------------- | --------------------------------------------------------------------- |
+| `revert`      | every failure sits in one owning area, attributable to one commit     |
+| `quarantine`  | failures span several areas, or the culprit range is not attributable |
+| `investigate` | the failures carry no `area` at all                                   |
+
+`investigate` is deliberate: a confident recommendation derived from absent data
+is worse than no recommendation.
+
+## Abstention
+
+A store with no run for the requested branch is a **zero denominator**. The
+skill prints a loud `ABSTAINED` line and never the green copy — "main looks
+fine" derived from zero observations is the false-green this repo keeps
+re-learning. Under `--strict` that abstention exits `3`.
+
+## Invocation
+
+```bash
+# Advisory (exit 0 whatever it finds) — the default:
+canary skills run canary-screech -- --history test-results/reports/history-v2.jsonl
+
+# Watch a non-default branch and write the artifact:
+canary skills run canary-screech -- \
+  --history test-results/reports/history-v2.jsonl \
+  --branch release/7.x \
+  --out test-results/reports/screech.md
+
+# Gate a workflow on it:
+canary skills run canary-screech -- \
+  --history test-results/reports/history-v2.jsonl --strict
+
+# Usage and the full flag list (exits 0):
+canary skills run canary-screech -- --help
+```
+
+`--history` is required. `--branch` defaults to `main`.
+
+### Exit codes
+
+| Code | Meaning                                           |
+| ---- | ------------------------------------------------- |
+| `0`  | advisory mode always; or `--strict` and green     |
+| `1`  | `--strict` and the branch is red; or a read error |
+| `2`  | usage error                                       |
+| `3`  | `--strict` and the skill abstained                |
+
+## CI wiring (GitHub Actions)
+
+Run it on a schedule or after the default-branch test job, with `if: always()`
+so a failed test step does not suppress the siren:
+
+```yaml
+- name: Broken-main siren
+  if: always()
+  run: |
+    canary skills run canary-screech -- \
+      --history test-results/reports/history-v2.jsonl \
+      --out test-results/reports/screech.md \
+      --strict
+```

package/agents/skills/claude-code/canary-screech/scripts/blast.mjs

@@ -0,0 +1,125 @@
+// blast -- render the one-page broken-main blast. Pure.
+//
+// Three outputs from one assessment, because the same fact has three audiences:
+//   markdown     the standalone artifact a human opens
+//   annotations  a single `::error` line so the GitHub Checks UI shows it
+//   chatBlock    plain text the on-call pastes into whatever chat they use
+//
+// The chat block is emitted, never posted. The skill has no credentials, no
+// webhook, and no write access to anything but the artifact path it was given.
+
+const CROSS = '\u274c'; // cross mark
+const CHECK = '\u2705'; // white heavy check mark
+const DASH = '\u2014'; // em dash
+
+/** The first meaningful line of an error blob, clipped. */
+function firstLine(error, limit = 160) {
+  if (!error) return '(no error message)';
+  for (const raw of String(error).split(/\r\n|\r|\n/)) {
+    const line = raw.trim();
+    if (line) return line.slice(0, limit);
+  }
+  return '(no error message)';
+}
+
+const NEXT_STEP = {
+  revert: 'Revert the culprit commit. One area, one attributable commit.',
+  quarantine:
+    'Quarantine the failing tests and open a tracking issue. The break is not cleanly attributable to one commit.',
+  investigate:
+    'Investigate before acting. The failing tests carry no owning area, so neither a revert nor a quarantine can be aimed.',
+};
+
+/**
+ * Render the blast.
+ *
+ * @param {{branch: string, assessment: object, cluster: object|null}} input
+ * @returns {{markdown: string, annotations: string[], chatBlock: string}}
+ */
+export function renderBlast({ branch, assessment, cluster }) {
+  if (assessment.state === 'abstained') {
+    const text =
+      `${CROSS} canary-screech ABSTAINED ${DASH} the run-history store holds no run for \`${branch}\`.\n\n` +
+      'Zero observations is not a healthy branch. Point `--history` at a store ' +
+      'that this branch actually writes to, or wire the suite to record runs.';
+    return {
+      markdown: `# canary-screech ${DASH} ${branch}\n\n${text}\n`,
+      annotations: [],
+      chatBlock: text,
+    };
+  }
+
+  if (assessment.state === 'green') {
+    const text = `${CHECK} \`${branch}\` is green as of ${assessment.latest.commit_sha ?? '(unknown commit)'}.`;
+    return {
+      markdown: `# canary-screech ${DASH} ${branch}\n\n${text}\n`,
+      annotations: [],
+      chatBlock: text,
+    };
+  }
+
+  const { culpritRange, firstRed } = assessment;
+  const from =
+    culpritRange.from ?? '(unknown - no green run recorded before the break)';
+  const to = culpritRange.to ?? '(unknown)';
+  const failureCount = cluster.clusters.reduce((n, c) => n + c.tests.length, 0);
+
+  const chatLines = [
+    `${CROSS} ${branch} is RED ${DASH} ${failureCount} failing test${failureCount === 1 ? '' : 's'}`,
+    `culprit range: ${from}..${to}`,
+    `owning area:   ${cluster.owningArea ?? '(none recorded)'}`,
+    `recommendation: ${cluster.recommendation.toUpperCase()} ${DASH} ${NEXT_STEP[cluster.recommendation]}`,
+    `first red run: ${firstRed.run_id} (${firstRed.suite}) at ${firstRed.timestamp}`,
+  ];
+  const chatBlock = chatLines.join('\n');
+
+  const lines = [
+    `# ${CROSS} canary-screech ${DASH} \`${branch}\` is red`,
+    '',
+    `**First red run:** \`${firstRed.run_id}\` (${firstRed.suite}) at ${firstRed.timestamp}`,
+    '',
+    '## Culprit commit range',
+    '',
+    `\`${from}\` .. \`${to}\``,
+    '',
+  ];
+  if (!culpritRange.bounded) {
+    lines.push(
+      '> The lower bound is unknown: the store holds no green run for this ' +
+        'branch before the break, so the range below is open-ended.',
+      '',
+    );
+  }
+  lines.push('## Failure cluster', '');
+  for (const c of cluster.clusters) {
+    lines.push(`### ${c.category} (${c.tests.length})`, '');
+    for (const t of c.tests) {
+      lines.push(`- \`${t.test_name}\` ${DASH} ${firstLine(t.error_text)}`);
+    }
+    lines.push('');
+  }
+  lines.push(
+    '## Owning area',
+    '',
+    cluster.areas.length
+      ? cluster.areas.map((a) => `- \`${a.area}\` (${a.count})`).join('\n')
+      : '_No failing test carries an `area`, so ownership could not be derived._',
+    '',
+    '## Recommendation',
+    '',
+    `**${cluster.recommendation.toUpperCase()}** ${DASH} ${NEXT_STEP[cluster.recommendation]}`,
+    '',
+    '## Chat-ready block',
+    '',
+    '```text',
+    chatBlock,
+    '```',
+    '',
+  );
+
+  const annotations = [
+    `::error title=Broken branch::${branch} is red ${DASH} ${failureCount} failing test${failureCount === 1 ? '' : 's'} in ${cluster.owningArea ?? 'an unrecorded area'}; culprit ${from}..${to}; recommendation: ${cluster.recommendation}`,
+  ];
+
+  return { markdown: lines.join('\n'), annotations, chatBlock };
+}