From dc2b9ea1218074eeb48961ae0af2290c23d24dfb Mon Sep 17 00:00:00 2001
From: Raphael Hehl <7577984+RaHehl@users.noreply.github.com>
Date: Wed, 11 Nov 2026 21:17:40 +0100
Subject: [PATCH 1/2] feat(core): read integration issue context from core

---
 src/github/helpers/dev-file.ts                |  72 +++++++++
 src/github/helpers/integration-manifest.ts    |  58 +------
 .../home-assistant-core/issue-context.ts      |   6 +-
 .../rules/issue-context.ts                    |  69 ++++++--
 .../rules/issue-context.test.ts               | 151 ++++++++++++++++++
 tests/setup.ts                                |   8 +-
 6 files changed, 292 insertions(+), 72 deletions(-)
 create mode 100644 src/github/helpers/dev-file.ts
 create mode 100644 tests/github/manifests/home-assistant-core/rules/issue-context.test.ts

diff --git a/src/github/helpers/dev-file.ts b/src/github/helpers/dev-file.ts
new file mode 100644
index 0000000..8f73380
--- /dev/null
+++ b/src/github/helpers/dev-file.ts
@@ -0,0 +1,72 @@
+import { log } from "../../log.js";
+import { fetchWithTimeout } from "../../util/fetch.js";
+
+// Long: these files change only by PR, and every reader re-evaluates on later
+// events, so a stale read corrects itself.
+const HIT_TTL_MS = 6 * 60 * 60 * 1000;
+
+// Short: a 404 means "not on dev *yet*", and a file merged minutes ago must
+// not stay invisible for six hours.
+const MISS_TTL_MS = 5 * 60 * 1000;
+
+// Core's domain grammar. Callers pass user input (command arguments, link
+// segments, directory names, labels), which otherwise ends up in the URL.
+const DOMAIN = /^[a-z0-9_]+$/;
+
+const resets: (() => void)[] = [];
+
+/**
+ * A cached reader for one file in every integration directory on core's dev
+ * branch, e.g. `manifest.json`. `read` turns a successful response into the
+ * value (undefined when it is not usable). Cached across deliveries, one
+ * entry per domain; concurrent readers share one fetch; a failed fetch keeps
+ * the last good value and is not cached.
+ */
+export function devComponentFile<T>(
+  file: string,
+  read: (res: Response, domain: string) => Promise<T | undefined>,
+): (domain: string) => Promise<T | undefined> {
+  const byDomain = new Map<string, { value?: T; fetchedAt: number }>();
+  const inflight = new Map<string, Promise<T | undefined>>();
+  resets.push(() => {
+    byDomain.clear();
+    inflight.clear();
+  });
+
+  async function fetchFromDev(domain: string): Promise<T | undefined> {
+    let value: T | undefined;
+    try {
+      const res = await fetchWithTimeout(
+        `https://raw.githubusercontent.com/home-assistant/core/dev/homeassistant/components/${domain}/${file}`,
+      );
+      if (res.ok) value = await read(res, domain);
+    } catch (err) {
+      log.warn("devComponentFile: fetch failed", { domain, file, error: String(err) });
+      // Uncached: a transient failure must not pin a miss.
+      return byDomain.get(domain)?.value;
+    }
+    byDomain.set(domain, { value, fetchedAt: Date.now() });
+    return value;
+  }
+
+  return (domain) => {
+    if (!DOMAIN.test(domain)) return Promise.resolve(undefined);
+    const cached = byDomain.get(domain);
+    if (cached) {
+      const ttl = cached.value === undefined ? MISS_TTL_MS : HIT_TTL_MS;
+      if (Date.now() - cached.fetchedAt < ttl) return Promise.resolve(cached.value);
+    }
+
+    let pending = inflight.get(domain);
+    if (!pending) {
+      pending = fetchFromDev(domain).finally(() => inflight.delete(domain));
+      inflight.set(domain, pending);
+    }
+    return pending;
+  };
+}
+
+/** Test hook: drop every cache so a case sees the files it serves. */
+export function resetDevComponentFiles(): void {
+  for (const reset of resets) reset();
+}
diff --git a/src/github/helpers/integration-manifest.ts b/src/github/helpers/integration-manifest.ts
index 691e6b2..c3d8ab2 100644
--- a/src/github/helpers/integration-manifest.ts
+++ b/src/github/helpers/integration-manifest.ts
@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { log } from "../../log.js";
-import { fetchWithTimeout } from "../../util/fetch.js";
+import { devComponentFile } from "./dev-file.js";
 
 export enum QualityScale {
   NO_SCORE = "No score",
@@ -43,60 +43,10 @@ export function parseIntegrationManifest(
   return parsed.data;
 }
 
-// Long: manifests change only by PR, and every reader re-evaluates on later
-// events, so a stale read corrects itself.
-const MANIFEST_TTL_MS = 6 * 60 * 60 * 1000;
-
-// Short: a 404 means "not on dev *yet*", and an integration merged minutes ago
-// must not stay invisible for six hours.
-const MISS_TTL_MS = 5 * 60 * 1000;
-
-// Core's domain grammar. Callers pass user input (command arguments, link
-// segments, directory names), which otherwise ends up in the fetched URL.
-const DOMAIN = /^[a-z0-9_]+$/;
-
-/** Cross-event cache, one entry per domain (~1500 at most). */
-const byDomain = new Map<string, { manifest?: IntegrationManifest; fetchedAt: number }>();
-const inflight = new Map<string, Promise<IntegrationManifest | undefined>>();
-
-async function fetchFromDev(domain: string): Promise<IntegrationManifest | undefined> {
-  let manifest: IntegrationManifest | undefined;
-  try {
-    const res = await fetchWithTimeout(
-      `https://raw.githubusercontent.com/home-assistant/core/dev/homeassistant/components/${domain}/manifest.json`,
-    );
-    if (res.ok) manifest = parseIntegrationManifest(await res.json(), `dev:${domain}`);
-  } catch (err) {
-    log.warn("fetchIntegrationManifest: fetch failed", { domain, error: String(err) });
-    // Uncached: a transient failure must not pin a miss.
-    return byDomain.get(domain)?.manifest;
-  }
-  byDomain.set(domain, { manifest, fetchedAt: Date.now() });
-  return manifest;
-}
-
 /**
  * The manifest as shipped on core's dev branch, or undefined if there is none
  * there. Cached across deliveries; concurrent readers share one fetch.
  */
-export function fetchIntegrationManifest(domain: string): Promise<IntegrationManifest | undefined> {
-  if (!DOMAIN.test(domain)) return Promise.resolve(undefined);
-  const cached = byDomain.get(domain);
-  if (cached) {
-    const ttl = cached.manifest ? MANIFEST_TTL_MS : MISS_TTL_MS;
-    if (Date.now() - cached.fetchedAt < ttl) return Promise.resolve(cached.manifest);
-  }
-
-  let pending = inflight.get(domain);
-  if (!pending) {
-    pending = fetchFromDev(domain).finally(() => inflight.delete(domain));
-    inflight.set(domain, pending);
-  }
-  return pending;
-}
-
-/** Test hook: drop the cache so a case sees the manifests it serves. */
-export function resetIntegrationManifests(): void {
-  byDomain.clear();
-  inflight.clear();
-}
+export const fetchIntegrationManifest = devComponentFile("manifest.json", async (res, domain) =>
+  parseIntegrationManifest(await res.json(), `dev:${domain}`),
+);
diff --git a/src/github/manifests/home-assistant-core/issue-context.ts b/src/github/manifests/home-assistant-core/issue-context.ts
index 86e2c31..6d1fe1e 100644
--- a/src/github/manifests/home-assistant-core/issue-context.ts
+++ b/src/github/manifests/home-assistant-core/issue-context.ts
@@ -1,7 +1,9 @@
 /**
  * Per-label reporting guidance shown on the issue dashboard, ported from the
- * legacy bot's `data/github/issue_context.yaml`. The generic duplicate-check
- * message lives in the dashboard's issue intro, not here.
+ * legacy bot's `data/github/issue_context.yaml`. An integration's
+ * `issue_context.md` in core takes precedence over its entry here. The
+ * generic duplicate-check message lives in the dashboard's issue intro, not
+ * here.
  */
 export const coreIssueContext: Record<string, string> = {
   "custom integration":
diff --git a/src/github/manifests/home-assistant-core/rules/issue-context.ts b/src/github/manifests/home-assistant-core/rules/issue-context.ts
index 6d6af53..4b7af59 100644
--- a/src/github/manifests/home-assistant-core/rules/issue-context.ts
+++ b/src/github/manifests/home-assistant-core/rules/issue-context.ts
@@ -1,31 +1,75 @@
+import { log } from "../../../../log.js";
+import { neutraliseMentions } from "../../../../util/markdown.js";
 import { EventType } from "../../../engine/event.js";
 import type { RuleContext } from "../../../engine/model/rule-context.js";
 import { on } from "../../../engine/rule.js";
 import type { Rule, RuleOutput } from "../../../engine/types.js";
+import { devComponentFile } from "../../../helpers/dev-file.js";
 import { INTEGRATION_LABEL_PREFIX } from "../../../helpers/integration-domains.js";
 import { itemIntegrationDomains } from "../helpers/integration-domains.js";
 
 type HandledEvent = EventType.ISSUES_OPENED | EventType.ISSUES_LABELED | EventType.ISSUES_ON_DEMAND;
 
+/** The file an integration keeps its reporting guidance in, inside core. */
+export const ISSUE_CONTEXT_FILE = "issue_context.md";
+
+/** Longer guidance is ignored; it belongs in the integration's docs. */
+export const MAX_ISSUE_CONTEXT_LENGTH = 2000;
+
+/**
+ * An integration's guidance as text the dashboard can carry: no mentions that
+ * notify, no HTML comment that would hide the rest of the dashboard or pose
+ * as its state. Undefined when the file is empty or too long.
+ */
+export function issueContextText(raw: string, domain: string): string | undefined {
+  const text = raw.trim();
+  if (!text) return;
+  if (text.length > MAX_ISSUE_CONTEXT_LENGTH) {
+    log.warn("issueContext: file too long, ignored", { domain, length: text.length });
+    return;
+  }
+  return neutraliseMentions(text).replaceAll("<!--", "&lt;!--");
+}
+
+const fetchIssueContext = devComponentFile(ISSUE_CONTEXT_FILE, async (res, domain) =>
+  issueContextText(await res.text(), domain),
+);
+
 /**
- * Per-label reporting guidance on the issue dashboard (keys are full label
- * names, e.g. `integration: zha`, `custom integration`). Generic advice
- * lives in the dashboard's issue intro; this rule only carries extras and
- * fills the `reporting-guidance` template block.
+ * Reporting guidance on the issue dashboard. Integrations keep theirs in core
+ * as `homeassistant/components/<domain>/issue_context.md`, read from dev;
+ * `labels` holds guidance by full label name (e.g. `custom integration`),
+ * and for integrations that have no file in core yet. Generic advice lives
+ * in the dashboard's issue intro; this rule only carries extras and fills the
+ * `reporting-guidance` template block.
  */
 export function issueContext(labels: Record<string, string>): Rule {
   async function evaluate(ctx: RuleContext<HandledEvent>): Promise<RuleOutput | undefined> {
-    if ("label" in ctx.event && !(ctx.event.label in labels)) return;
+    if (
+      "label" in ctx.event &&
+      !(ctx.event.label in labels) &&
+      !ctx.event.label.startsWith(INTEGRATION_LABEL_PREFIX)
+    )
+      return;
     // Plain rule (blocks, not check()): guard closed issues itself.
     if ((await ctx.target.state()) !== "open") return;
 
-    // Labels on the issue plus the integration labels it's about, so guidance
-    // shows up on opened without waiting for set-integration.
-    const derived = (await itemIntegrationDomains(ctx)).map(
-      (d) => `${INTEGRATION_LABEL_PREFIX}${d}`,
+    // Labels on the issue plus the integrations it's about, so guidance shows
+    // up on opened without waiting for set-integration.
+    const domains = await itemIntegrationDomains(ctx);
+    const fromCore = new Map<string, string | undefined>(
+      await Promise.all(
+        domains.map(
+          async (domain) =>
+            [`${INTEGRATION_LABEL_PREFIX}${domain}`, await fetchIssueContext(domain)] as const,
+        ),
+      ),
     );
-    const effective = new Set([...(await ctx.target.labels()), ...derived]);
-    const paragraphs = [...effective].flatMap((label) => (labels[label] ? [labels[label]] : []));
+    const effective = new Set([...(await ctx.target.labels()), ...fromCore.keys()]);
+    const paragraphs = [...effective].flatMap((label) => {
+      const text = fromCore.get(label) ?? labels[label];
+      return text ? [text] : [];
+    });
 
     return {
       blocks: [
@@ -39,7 +83,8 @@ export function issueContext(labels: Record<string, string>): Rule {
 
   return {
     name: "issue-context",
-    description: "Shows per-label reporting guidance on the issue dashboard",
+    description:
+      "Shows reporting guidance for the issue's labels and integrations on the dashboard",
     events: on(
       [EventType.ISSUES_OPENED, EventType.ISSUES_LABELED, EventType.ISSUES_ON_DEMAND],
       evaluate,
diff --git a/tests/github/manifests/home-assistant-core/rules/issue-context.test.ts b/tests/github/manifests/home-assistant-core/rules/issue-context.test.ts
new file mode 100644
index 0000000..f089102
--- /dev/null
+++ b/tests/github/manifests/home-assistant-core/rules/issue-context.test.ts
@@ -0,0 +1,151 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { EventType } from "../../../../../src/github/engine/event.js";
+import {
+  issueContext,
+  issueContextText,
+  MAX_ISSUE_CONTEXT_LENGTH,
+} from "../../../../../src/github/manifests/home-assistant-core/rules/issue-context.js";
+import { expectLoggedErrors } from "../../../../helpers/log-guard.js";
+import { createMockIssueContext, runRule } from "../../../helpers/mock-context.js";
+
+const rule = issueContext({
+  "custom integration": "Report it upstream.",
+  "integration: shelly": "Shelly guidance from the bot.",
+  "integration: zha": "ZHA guidance from the bot.",
+});
+
+const ZHA = { domain: "zha", name: "Zigbee Home Automation" };
+const HUE = { domain: "hue", name: "Philips Hue" };
+
+/** Serves manifests and issue_context.md files off "dev"; the rest 404s. */
+function mockDev(files: Record<string, unknown>) {
+  const fetch = vi.fn(async (input: string | URL | Request) => {
+    const url = String(input);
+    const path = url.split("/homeassistant/components/")[1] ?? "";
+    if (!(path in files)) return { ok: false, status: 404 } as Response;
+    const body = files[path];
+    if (body instanceof Error) throw body;
+    return {
+      ok: true,
+      status: 200,
+      json: async () => body,
+      text: async () => String(body),
+    } as Response;
+  });
+  vi.stubGlobal("fetch", fetch);
+  return fetch;
+}
+
+function issue(labels: string[], { body = "", label }: { body?: string; label?: string } = {}) {
+  return createMockIssueContext({
+    eventType: label ? EventType.ISSUES_LABELED : EventType.ISSUES_OPENED,
+    payload: {
+      ...(label ? { action: "labeled", label: { name: label } } : {}),
+      issue: { body, labels: labels.map((name) => ({ name })) },
+    },
+  });
+}
+
+async function paragraphs(context: ReturnType<typeof issue>) {
+  const result = await runRule(rule, context);
+  return (result?.blocks[0]?.args as { paragraphs: string[] } | null)?.paragraphs ?? null;
+}
+
+describe("issue-context", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("prefers the integration's file in core over the map", async () => {
+    mockDev({ "zha/issue_context.md": "Attach ZHA diagnostics.\n" });
+
+    expect(await paragraphs(issue(["integration: zha"]))).toEqual(["Attach ZHA diagnostics."]);
+  });
+
+  it("uses the map for an integration without a file", async () => {
+    mockDev({});
+
+    expect(await paragraphs(issue(["integration: shelly"]))).toEqual([
+      "Shelly guidance from the bot.",
+    ]);
+  });
+
+  it("finds the integration through the docs link before it is labelled", async () => {
+    mockDev({ "hue/manifest.json": HUE, "hue/issue_context.md": "Hue bridge firmware?" });
+    const body = "Broken since today, see https://www.home-assistant.io/integrations/hue/";
+
+    expect(await paragraphs(issue([], { body }))).toEqual(["Hue bridge firmware?"]);
+  });
+
+  it("keeps label order and adds each integration once", async () => {
+    mockDev({
+      "zha/manifest.json": ZHA,
+      "zha/issue_context.md": "Attach ZHA diagnostics.",
+      "hue/issue_context.md": "Hue bridge firmware?",
+    });
+    const body = "https://www.home-assistant.io/integrations/zha/";
+
+    expect(
+      await paragraphs(
+        issue(["custom integration", "integration: zha", "integration: hue"], { body }),
+      ),
+    ).toEqual(["Report it upstream.", "Attach ZHA diagnostics.", "Hue bridge firmware?"]);
+  });
+
+  it("clears the block when nothing applies", async () => {
+    mockDev({});
+
+    expect(await paragraphs(issue(["integration: hue"]))).toBeNull();
+  });
+
+  it("falls back to the map when dev cannot be read", async () => {
+    expectLoggedErrors();
+    mockDev({ "zha/issue_context.md": new Error("rate limited") });
+
+    expect(await paragraphs(issue(["custom integration", "integration: zha"]))).toEqual([
+      "Report it upstream.",
+      "ZHA guidance from the bot.",
+    ]);
+  });
+
+  it("reads each file once across events", async () => {
+    const fetch = mockDev({ "zha/issue_context.md": "Attach ZHA diagnostics." });
+
+    await paragraphs(issue(["integration: zha"]));
+    await paragraphs(issue(["integration: zha"]));
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("runs when an integration label is added", async () => {
+    mockDev({ "hue/issue_context.md": "Hue bridge firmware?" });
+
+    expect(await paragraphs(issue(["integration: hue"], { label: "integration: hue" }))).toEqual([
+      "Hue bridge firmware?",
+    ]);
+  });
+
+  it("skips other labels", async () => {
+    const fetch = mockDev({});
+
+    const result = await runRule(rule, issue(["bug"], { label: "bug" }));
+    expect(result).toBeUndefined();
+    expect(fetch).not.toHaveBeenCalled();
+  });
+});
+
+describe("issueContextText", () => {
+  it("defuses mentions and HTML comments", () => {
+    expect(issueContextText("Ask @someone\n<!-- ha-bot-state:{} -->\n", "zha")).toBe(
+      "Ask @​someone\n&lt;!-- ha-bot-state:{} -->",
+    );
+  });
+
+  it("ignores empty files", () => {
+    expect(issueContextText(" \n", "zha")).toBeUndefined();
+  });
+
+  it("ignores files that are too long", () => {
+    expectLoggedErrors();
+    expect(issueContextText("x".repeat(MAX_ISSUE_CONTEXT_LENGTH + 1), "zha")).toBeUndefined();
+  });
+});
diff --git a/tests/setup.ts b/tests/setup.ts
index 0ab4a69..a4f33f7 100644
--- a/tests/setup.ts
+++ b/tests/setup.ts
@@ -1,12 +1,12 @@
 import { afterEach, beforeEach } from "vitest";
-import { resetIntegrationManifests } from "../src/github/helpers/integration-manifest.js";
+import { resetDevComponentFiles } from "../src/github/helpers/dev-file.js";
 import { resetItemLocks } from "../src/github/item-lock.js";
 // Importing the guard silences src/log.js for the whole run (see the module).
 import { verifyLogGuard } from "./helpers/log-guard.js";
 
-// The manifest cache spans deliveries in production; each test case must see
-// the manifests it serves, not the previous case's.
-beforeEach(resetIntegrationManifests);
+// The dev file caches span deliveries in production; each test case must see
+// the files it serves, not the previous case's.
+beforeEach(resetDevComponentFiles);
 
 // Lock queues span deliveries in production; a case must not wait on another's.
 beforeEach(resetItemLocks);

From c43a66afc771f0d09e4e77f796dac2db0ad8916f Mon Sep 17 00:00:00 2001
From: Raphael Hehl <7577984+RaHehl@users.noreply.github.com>
Date: Wed, 11 Nov 2026 21:26:08 +0100
Subject: [PATCH 2/2] fix(core): keep the last good dev file on HTTP errors,
 simplify issue context

---
 .../status/templates/dashboard-issue.md       |  1 +
 src/github/helpers/dev-file.ts                |  8 ++--
 .../rules/issue-context.ts                    | 40 ++++++-----------
 src/util/markdown.ts                          |  5 +++
 tests/github/engine/status/render.test.ts     |  6 +--
 .../helpers/integration-manifest.test.ts      | 14 ++++++
 .../rules/issue-context.test.ts               | 44 +++++++------------
 7 files changed, 57 insertions(+), 61 deletions(-)

diff --git a/src/github/engine/status/templates/dashboard-issue.md b/src/github/engine/status/templates/dashboard-issue.md
index 0040779..9b06e91 100644
--- a/src/github/engine/status/templates/dashboard-issue.md
+++ b/src/github/engine/status/templates/dashboard-issue.md
@@ -8,6 +8,7 @@ Before we dive in, please make sure this isn't a duplicate by searching through
 **Reporting guidance**
 {{#paragraphs}}
 {{.}}
+
 {{/paragraphs}}
 
 {{/blocks.reporting-guidance}}
diff --git a/src/github/helpers/dev-file.ts b/src/github/helpers/dev-file.ts
index 8f73380..1522fee 100644
--- a/src/github/helpers/dev-file.ts
+++ b/src/github/helpers/dev-file.ts
@@ -5,7 +5,7 @@ import { fetchWithTimeout } from "../../util/fetch.js";
 // events, so a stale read corrects itself.
 const HIT_TTL_MS = 6 * 60 * 60 * 1000;
 
-// Short: a 404 means "not on dev *yet*", and a file merged minutes ago must
+// Short: a missing or unusable file may be fixed on dev any minute, and must
 // not stay invisible for six hours.
 const MISS_TTL_MS = 5 * 60 * 1000;
 
@@ -19,8 +19,9 @@ const resets: (() => void)[] = [];
  * A cached reader for one file in every integration directory on core's dev
  * branch, e.g. `manifest.json`. `read` turns a successful response into the
  * value (undefined when it is not usable). Cached across deliveries, one
- * entry per domain; concurrent readers share one fetch; a failed fetch keeps
- * the last good value and is not cached.
+ * entry per domain; concurrent readers share one fetch. Only a 404 counts as
+ * a miss: any other failure keeps the last good value and is not cached.
+ * Call once per file, at module scope.
  */
 export function devComponentFile<T>(
   file: string,
@@ -40,6 +41,7 @@ export function devComponentFile<T>(
         `https://raw.githubusercontent.com/home-assistant/core/dev/homeassistant/components/${domain}/${file}`,
       );
       if (res.ok) value = await read(res, domain);
+      else if (res.status !== 404) throw new Error(`HTTP ${res.status}`);
     } catch (err) {
       log.warn("devComponentFile: fetch failed", { domain, file, error: String(err) });
       // Uncached: a transient failure must not pin a miss.
diff --git a/src/github/manifests/home-assistant-core/rules/issue-context.ts b/src/github/manifests/home-assistant-core/rules/issue-context.ts
index 4b7af59..f7ca811 100644
--- a/src/github/manifests/home-assistant-core/rules/issue-context.ts
+++ b/src/github/manifests/home-assistant-core/rules/issue-context.ts
@@ -1,5 +1,5 @@
 import { log } from "../../../../log.js";
-import { neutraliseMentions } from "../../../../util/markdown.js";
+import { defuseHtmlComments, neutraliseMentions } from "../../../../util/markdown.js";
 import { EventType } from "../../../engine/event.js";
 import type { RuleContext } from "../../../engine/model/rule-context.js";
 import { on } from "../../../engine/rule.js";
@@ -10,30 +10,22 @@ import { itemIntegrationDomains } from "../helpers/integration-domains.js";
 
 type HandledEvent = EventType.ISSUES_OPENED | EventType.ISSUES_LABELED | EventType.ISSUES_ON_DEMAND;
 
-/** The file an integration keeps its reporting guidance in, inside core. */
-export const ISSUE_CONTEXT_FILE = "issue_context.md";
-
-/** Longer guidance is ignored; it belongs in the integration's docs. */
-export const MAX_ISSUE_CONTEXT_LENGTH = 2000;
+// Longer guidance belongs in the integration's docs.
+const MAX_LENGTH = 2000;
 
 /**
- * An integration's guidance as text the dashboard can carry: no mentions that
- * notify, no HTML comment that would hide the rest of the dashboard or pose
- * as its state. Undefined when the file is empty or too long.
+ * An integration's guidance from core, as text the dashboard can carry: no
+ * mentions that notify, no HTML comment that hides the rest or poses as the
+ * dashboard's state. Undefined when empty or too long.
  */
-export function issueContextText(raw: string, domain: string): string | undefined {
-  const text = raw.trim();
-  if (!text) return;
-  if (text.length > MAX_ISSUE_CONTEXT_LENGTH) {
+const fetchIssueContext = devComponentFile("issue_context.md", async (res, domain) => {
+  const text = (await res.text()).trim();
+  if (text.length > MAX_LENGTH) {
     log.warn("issueContext: file too long, ignored", { domain, length: text.length });
     return;
   }
-  return neutraliseMentions(text).replaceAll("<!--", "&lt;!--");
-}
-
-const fetchIssueContext = devComponentFile(ISSUE_CONTEXT_FILE, async (res, domain) =>
-  issueContextText(await res.text(), domain),
-);
+  return text ? defuseHtmlComments(neutraliseMentions(text)) : undefined;
+});
 
 /**
  * Reporting guidance on the issue dashboard. Integrations keep theirs in core
@@ -57,13 +49,9 @@ export function issueContext(labels: Record<string, string>): Rule {
     // Labels on the issue plus the integrations it's about, so guidance shows
     // up on opened without waiting for set-integration.
     const domains = await itemIntegrationDomains(ctx);
-    const fromCore = new Map<string, string | undefined>(
-      await Promise.all(
-        domains.map(
-          async (domain) =>
-            [`${INTEGRATION_LABEL_PREFIX}${domain}`, await fetchIssueContext(domain)] as const,
-        ),
-      ),
+    const texts = await Promise.all(domains.map((domain) => fetchIssueContext(domain)));
+    const fromCore = new Map(
+      domains.map((domain, i) => [`${INTEGRATION_LABEL_PREFIX}${domain}`, texts[i]]),
     );
     const effective = new Set([...(await ctx.target.labels()), ...fromCore.keys()]);
     const paragraphs = [...effective].flatMap((label) => {
diff --git a/src/util/markdown.ts b/src/util/markdown.ts
index 2d539da..9947f9c 100644
--- a/src/util/markdown.ts
+++ b/src/util/markdown.ts
@@ -16,3 +16,8 @@ export function codeSpan(text: string): string {
 export function neutraliseMentions(text: string): string {
   return text.replace(/@(?=\w)/g, "@\u200B");
 }
+
+/** `text` with HTML comment openers defused, so it cannot hide or forge the bot's markers. */
+export function defuseHtmlComments(text: string): string {
+  return text.replaceAll("<!--", "&lt;!--");
+}
diff --git a/tests/github/engine/status/render.test.ts b/tests/github/engine/status/render.test.ts
index 2ffe2be..fc90f67 100644
--- a/tests/github/engine/status/render.test.ts
+++ b/tests/github/engine/status/render.test.ts
@@ -253,9 +253,9 @@ describe("status renderer", () => {
       });
       expect(result).not.toContain("## Checks");
       expect(result).toContain("**Reporting guidance**");
-      // Paragraphs render on consecutive lines (single newlines — GitHub
-      // comments treat those as line breaks).
-      expect(result).toContain("First advice.\nSecond advice.");
+      // A blank line between paragraphs, so one ending in a list or table
+      // cannot swallow the next.
+      expect(result).toContain("First advice.\n\nSecond advice.");
     });
 
     it("hidden blocks leave no trace in body or state", () => {
diff --git a/tests/github/helpers/integration-manifest.test.ts b/tests/github/helpers/integration-manifest.test.ts
index 4c2f66e..bba68b7 100644
--- a/tests/github/helpers/integration-manifest.test.ts
+++ b/tests/github/helpers/integration-manifest.test.ts
@@ -101,4 +101,18 @@ describe("fetchIntegrationManifest", () => {
     expect(await fetchIntegrationManifest("hue")).toMatchObject({ domain: "hue" });
     expect(fetch).toHaveBeenCalledTimes(1);
   });
+
+  it("keeps the last good manifest when dev answers with an error", async () => {
+    expectLoggedErrors(); // the transient-failure warn is the path under test
+    vi.useFakeTimers();
+    mockFetch({ hue: HUE });
+    await fetchIntegrationManifest("hue");
+    vi.advanceTimersByTime(6 * 60 * 60 * 1000 + 1000);
+
+    const fetch = vi.fn(async () => ({ ok: false, status: 503 }) as Response);
+    vi.stubGlobal("fetch", fetch);
+    expect(await fetchIntegrationManifest("hue")).toMatchObject({ domain: "hue" });
+    await fetchIntegrationManifest("hue");
+    expect(fetch).toHaveBeenCalledTimes(2);
+  });
 });
diff --git a/tests/github/manifests/home-assistant-core/rules/issue-context.test.ts b/tests/github/manifests/home-assistant-core/rules/issue-context.test.ts
index f089102..e9f331c 100644
--- a/tests/github/manifests/home-assistant-core/rules/issue-context.test.ts
+++ b/tests/github/manifests/home-assistant-core/rules/issue-context.test.ts
@@ -1,10 +1,6 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { EventType } from "../../../../../src/github/engine/event.js";
-import {
-  issueContext,
-  issueContextText,
-  MAX_ISSUE_CONTEXT_LENGTH,
-} from "../../../../../src/github/manifests/home-assistant-core/rules/issue-context.js";
+import { issueContext } from "../../../../../src/github/manifests/home-assistant-core/rules/issue-context.js";
 import { expectLoggedErrors } from "../../../../helpers/log-guard.js";
 import { createMockIssueContext, runRule } from "../../../helpers/mock-context.js";
 
@@ -47,8 +43,8 @@ function issue(labels: string[], { body = "", label }: { body?: string; label?:
 }
 
 async function paragraphs(context: ReturnType<typeof issue>) {
-  const result = await runRule(rule, context);
-  return (result?.blocks[0]?.args as { paragraphs: string[] } | null)?.paragraphs ?? null;
+  const [update] = (await runRule(rule, context))?.blocks ?? [];
+  return update?.block === "reporting-guidance" ? (update.args?.paragraphs ?? null) : null;
 }
 
 describe("issue-context", () => {
@@ -108,12 +104,19 @@ describe("issue-context", () => {
     ]);
   });
 
-  it("reads each file once across events", async () => {
-    const fetch = mockDev({ "zha/issue_context.md": "Attach ZHA diagnostics." });
+  it("defuses mentions and HTML comments", async () => {
+    mockDev({ "zha/issue_context.md": "Ask @someone\n<!-- ha-bot-state:{} -->" });
 
-    await paragraphs(issue(["integration: zha"]));
-    await paragraphs(issue(["integration: zha"]));
-    expect(fetch).toHaveBeenCalledTimes(1);
+    expect(await paragraphs(issue(["integration: zha"]))).toEqual([
+      "Ask @\u200Bsomeone\n&lt;!-- ha-bot-state:{} -->",
+    ]);
+  });
+
+  it("ignores a file that is too long", async () => {
+    expectLoggedErrors();
+    mockDev({ "zha/issue_context.md": "x".repeat(2001) });
+
+    expect(await paragraphs(issue(["integration: zha"]))).toEqual(["ZHA guidance from the bot."]);
   });
 
   it("runs when an integration label is added", async () => {
@@ -132,20 +135,3 @@ describe("issue-context", () => {
     expect(fetch).not.toHaveBeenCalled();
   });
 });
-
-describe("issueContextText", () => {
-  it("defuses mentions and HTML comments", () => {
-    expect(issueContextText("Ask @someone\n<!-- ha-bot-state:{} -->\n", "zha")).toBe(
-      "Ask @​someone\n&lt;!-- ha-bot-state:{} -->",
-    );
-  });
-
-  it("ignores empty files", () => {
-    expect(issueContextText(" \n", "zha")).toBeUndefined();
-  });
-
-  it("ignores files that are too long", () => {
-    expectLoggedErrors();
-    expect(issueContextText("x".repeat(MAX_ISSUE_CONTEXT_LENGTH + 1), "zha")).toBeUndefined();
-  });
-});