@capagents/forgeqe 1.1.4 → 1.1.5

package/prompts/test-reviewer.md

@@ -24,22 +24,25 @@ A test is approved only when all these conditions are true:
 
 ## Problem types
 - correctness: the test does not do what the goal says, from start to end, or not reliably. Examples are a missing step or check, a weaker assertion, live values in assertions, and ForgeQE files that the test reads.
-- standards: the test passes and does what the goal says, but not in the way of the repository. Examples are test data in a page object, a method that is not generic, a hard wait, and scratch files.
+- standards: the test passes and does what the goal says, but not in the way of the repository. Examples are test data in a page object, a method that is not generic, a hard wait, an XPath or positional locator where a semantic one finds the element, a deprecated API of the installed framework version, and scratch files.
 
 ## Inputs
 - The message from ForgeQE: the goal, the checks that the browser agent made, and the files that this job changed, with their contents.
+- When the code graph is on: outlines of the classes that the changed code uses, the browser settings of the repository, and the code_* tools (code_outline Class.member gives one member's source).
 - ForgeQE gets those files from a comparison of the working tree with its state before the job.
 - The handoff, and other files of the repository, when a point depends on them.
 
 ## Rules
 Scope:
 - You MUST review from the changed files. You SHOULD read the handoff or other files only when a point depends on them.
+- You MUST NOT read a file to check a signature, a locator, or a browser setting that the outlines or the settings in the message give. To check a member's body, use code_outline Class.member.
 - You MUST NOT report files that the user changed or added before the job.
 - You MUST NOT report the files of ForgeQE: .forgeqe/, forgeqe.yaml, and llms.json.
 - In a file that the user changed before the job, you MUST review only the edits of this job.
 
 Locators and values:
 - You MUST NOT ask to replace locators and texts that the handoff took from its replay script and checks. They matched the live site.
+- When the message lists what the code graph of ForgeQE found, you MUST check each point in the changed files. A new member that locates an element an existing member already locates is a standards problem: the correction is to reuse the existing member. A brittle locator is a standards problem when the handoff gives a ✓ semantic locator for the same element.
 - You MUST accept a value that the test case names, such as a user name. Credentials MUST still come from the environment.
 
 Known defects (the handoff has a "Known defect" section):
@@ -52,7 +55,7 @@ Problems:
 - You MUST give all the problems in your first review. The coding agent then corrects them in one round.
 - For each problem, you MUST give the file, what is wrong, the correction, and its type: correctness or standards.
 - You MUST NOT ask for checks, data handling, or behaviour that the test case and the handoff do not ask for.
-- You MUST NOT report style points that the linters and conventions of the repository accept.
+- You MUST NOT report style points that the linters and conventions of the repository accept. Locators, waits, assertions, and deprecated APIs are not style points: judge them by the test rules, also when older tests of the repository do otherwise.
 - You MUST set approved to true when there is no correctness problem, also when there are standards problems. ForgeQE then asks for those corrections in one round.
 - When there is nothing to correct, you MUST approve.
 

package/prompts/test-rules.md

@@ -33,7 +33,11 @@ When the page of the test differs from what ForgeQE saw:
 - With blocked, you MUST give what you compared and what you saw, with the path of a screenshot or a trace.
 
 ## Code standards
-- You MUST follow the conventions of the repository: .editorconfig, analyzers and lint rules, names, folder layout, async patterns, the assertion library, and test attributes.
+- You MUST follow the conventions of the repository for its structure: .editorconfig, analyzers and lint rules, names, folder layout, base classes, fixtures, the assertion library, and test attributes.
+- You MUST write the code itself with the current best practice of the installed framework version, also when older tests of the repository do not. The test stack in your prompt gives the versions.
+- Locators, in this order of preference: role with accessible name, label, placeholder, text, test id, then CSS. You MUST NOT use XPath, or positions (nth, :nth-child, index) to pick an element, when one of the others finds it. In a framework without role locators, use its nearest semantic one (Testing Library queries, aria/ selectors) or a stable attribute.
+- You MUST assert with the retrying assertions of the framework, and wait for outcomes (an assertion, a URL, a response), never for time. You MUST NOT use sleeps, fixed timeouts, or deprecated APIs of the installed version.
+- You MUST NOT rewrite existing tests to modern style. When the code you reuse is in an older style, say so in notes.
 - The build MUST NOT get more warnings.
 - Page objects, components, and helpers MUST be generic. Each method takes the items that it acts on as parameters, and gives back what the test checks.
 - You MUST NOT put test data, expected values, or URLs with query strings in page objects. You MUST make locators from the parameters.
@@ -49,11 +53,11 @@ When the page of the test differs from what ForgeQE saw:
 ## Overlays and page versions
 - The notes of the browser agent tell when a cookie banner, sign-in prompt, promotion, or other overlay came into view, and what the agent did.
 - An overlay can come into view at a different time, or not at all. You MUST handle it where it comes into view.
-- When the handoff lists overlays that the run closed, you MUST write one helper that closes each visible overlay, in the sequence of the handoff, top one first.
+- When the handoff lists one overlay that the run closed, and the framework has an overlay handler (Playwright 1.42 and later: page.addLocatorHandler, Page.AddLocatorHandlerAsync), you MUST register the handler once, in the fixture or the base class setup, with the close control of the handoff.
+- When the handoff lists two or more overlays, or the framework has no overlay handler, you MUST write one helper that closes each visible overlay, in the sequence of the handoff, top one first.
 - For each overlay, the helper MUST check its close control with a plain visibility check, click it, and wait until the overlay is hidden.
 - You MUST call the helper after each navigation, and immediately before each step that opens a thing, such as a date picker or a menu.
-- You MUST NOT use the locator handlers of the framework (page.addLocatorHandler, Page.AddLocatorHandlerAsync) or a combined locator (locator.or) for overlays.
-- Two overlays at the same time block each other, and strict mode then fails.
+- You MUST NOT use overlay handlers or a combined locator (locator.or) for two or more overlays. They can show at the same time: the click of one handler is blocked by the other overlay, handlers do not run inside a handler, and strict mode fails on a combined locator.
 - You MUST do the flow again, not the tries of the agent.
 - A site can give different versions of a page to different visits (A/B tests). When you see a different version, you MUST write steps that work on each version.
 - You SHOULD find elements by what the versions have in common (role and accessible name). You MUST say in notes which versions you saw.

package/py/forgeqe_engine/browser.py

@@ -156,7 +156,7 @@ def _browserstack_caps(remote: Dict[str, Any]) -> Dict[str, Any]:
     if remote.get("name"):
         caps["name"] = str(remote["name"])
     if remote.get("local") is True:
-        caps["browserstack.local"] = True
+        caps["browserstack.local"] = "true"
     extra = remote.get("extra")
     if isinstance(extra, dict):
         caps.update(extra)

package/skills/dotnet-nunit-playwright/SKILL.md

@@ -26,7 +26,8 @@ agents: [scribe]
 - Locators: `Page.GetByRole(AriaRole.Button, new() { Name = "Save" })`, `GetByLabel`, `GetByPlaceholder`, `GetByText`, and `GetByTestId`, then CSS. Avoid XPath and position-based selectors.
 - Assert page state with retrying assertions: `await Expect(locator).ToBeVisibleAsync()`, `ToHaveTextAsync`, `ToHaveValueAsync`, and `await Expect(Page).ToHaveURLAsync(...)`. Use NUnit's `Assert.That` for plain values only, never on `await locator.IsVisibleAsync()`.
 - Wait for outcomes with `Page.WaitForURLAsync`, `Page.RunAndWaitForResponseAsync`, or an assertion.
-- Overlays that appear at random (cookie banners, surveys): register `Page.AddLocatorHandlerAsync(...)` in `[SetUp]` of the base class rather than clicking them inside a test.
+- One overlay that appears at random (a cookie banner, a survey): register `Page.AddLocatorHandlerAsync(...)` in `[SetUp]` of the base class (Playwright 1.42 and later) rather than clicking it inside a test.
+- Two or more that can show at once: write one helper that closes each visible one, top first, as the test rules describe. A handler's click is blocked while another overlay covers it.
 
 ## Data, secrets, attributes
 - Data: `[TestCase(...)]` or `[TestCaseSource(nameof(Cases))]`, or the repository's data files and builders. Compute dates when the test runs.

package/skills/playwright-typescript/SKILL.md

@@ -27,7 +27,8 @@ agents: [scribe]
 - Wait for outcomes, never time: no `page.waitForTimeout`. Use an assertion, `page.waitForURL`, or a `page.waitForResponse(...)` promise created before the click that triggers the request.
 
 ## Overlays that come and go
-- Cookie banners, chat prompts, and surveys that appear at random: register `page.addLocatorHandler(page.getByRole('button', { name: 'Accept all' }), async (button) => { await button.click() })` in a fixture or `beforeEach`, instead of clicking them inside the test.
+- One cookie banner, chat prompt, or survey that appears at random: register `page.addLocatorHandler(page.getByRole('button', { name: 'Accept all' }), async (button) => { await button.click() })` in a fixture or `beforeEach` (Playwright 1.42 and later), instead of clicking it inside the test.
+- Two or more that can show at once: write one helper that closes each visible one, top first, as the test rules describe. A handler's click is blocked while another overlay covers it.
 
 ## Data and secrets
 - Read secrets with `process.env.NAME`, and fail with a clear message when one is missing. If the config loads `dotenv`, add new names to `.env.example` without values.

package/src/brain/index.ts

@@ -120,7 +120,7 @@ export async function openBrain(opts: BrainOptions): Promise<Brain> {
   const cwd = realpathOr(opts.cwd)
   const context = (): ToolContext => ({ ...opts.context(), config, cwd })
   const tools = localToolServer({ tools: TOOLS, context, instructions: () => environmentNotes(context()), timeoutMs: TOOL_TIMEOUT_MS })
-  const external = opts.external || externalMcp(config)
+  const external = opts.external || externalMcp(config, Bun.which, process.env, { cwd })
   const notes = [environmentNotes(context()), ...externalNotes(external), ...(opts.notes || [])].filter(Boolean).join("\n")
   const readDirs = [...new Set([config.export.outDir, config.memory.dir, cwd].flatMap((d) => [path.resolve(d), realpathOr(d)]))]
   const onEvent = (e: CodeEvent) => {

package/src/capabilities/registry.ts

@@ -62,8 +62,12 @@ export const CAPABILITIES: Capability[] = [
     title: "Run any goal in a real browser",
     summary:
       "Carries out a plain-language goal in a real browser one step at a time and verifies the outcome, with screenshots, a report, and the steps it took. The browser comes from forgeqe.yaml: local Chrome or Chromium by default, or BrowserStack or TestMu AI/LambdaTest when configured. Page memory replays steps that already worked on a site, so repeat runs are faster and cheaper.",
-    tools: ["browser_run", "run_details", "page_memory"],
-    examples: ["Go to booking.com and search hotels in Mumbai for next weekend", "What does ForgeQE know about the checkout page?"],
+    tools: ["browser_run", "run_details", "page_memory", "browser_devices"],
+    examples: [
+      "Go to booking.com and search hotels in Mumbai for next weekend",
+      "What does ForgeQE know about the checkout page?",
+      "Add Chrome on Windows 11 and Chrome 128 on Windows 10 as TestMu devices, then run SHOP-12 on both",
+    ],
     requires: [{ kind: "live_model" }],
     limits: ["Web applications only: local Chrome or Chromium, or configured remote web grids such as BrowserStack and TestMu AI/LambdaTest; not native mobile or desktop applications."],
     docs: [
@@ -258,6 +262,24 @@ export const CAPABILITIES: Capability[] = [
     requires: [{ kind: "input", what: "a browser run (from browser_run or run_test_cases); new runs need a live model" }],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Visual comparison" }],
   },
+  {
+    id: "defect-intelligence",
+    area: "Quality",
+    title: "Defect intelligence: trends and prediction",
+    summary:
+      "Groups failures into defects, keeps their history across suites (new, known, gone, back again), and gives defect trends and where a change is likely to cause defects, with the cases to run first.",
+    tools: ["defect_trends", "predict_defects"],
+    examples: ["Which defects keep coming back?", "What can the changes since main break?"],
+    requires: [
+      { kind: "input", what: "suites run into one folder (suite.out_dir)" },
+      { kind: "command", command: "git", optional: true, why: "for predictions from the product's repository" },
+    ],
+    limits: ["Prediction is a heuristic from the saved suites and the change, not a trained model; its accuracy shows once suites have scored it."],
+    docs: [
+      { doc: "HOW_TO_USE.md", heading: "Bugs for failures" },
+      { doc: "HOW_TO_USE.md", heading: "Defect trends and prediction" },
+    ],
+  },
   {
     id: "release-readiness",
     area: "Release",
@@ -318,10 +340,16 @@ export const CAPABILITIES: Capability[] = [
   {
     id: "systems",
     area: "Systems",
-    title: "Work with Azure DevOps, Jira, and Confluence",
-    summary: "Reads anything in the configured systems (work items, issues, queries, boards, pages), makes changes the user asks for, and builds Azure DevOps dashboards and wiki pages.",
-    tools: ["query_api", "read_confluence", "create_ado_dashboard", "write_ado_wiki_page"],
-    examples: ["Show the open bugs in this sprint", "Read the checkout requirements from Confluence", "Make a dashboard of this sprint's test results"],
+    title: "Work with Azure DevOps, Jira, GitHub, and Confluence",
+    summary: "Reads anything in the configured systems (work items, issues, queries, boards, pages), makes changes the user asks for, puts run evidence (screenshots, reports) on work items and issues as attachments or comments, and builds Azure DevOps dashboards and wiki pages.",
+    tools: ["query_api", "read_confluence", "create_ado_dashboard", "write_ado_wiki_page", "attach_to_work_item"],
+    examples: [
+      "Show the open bugs in this sprint",
+      "Read the checkout requirements from Confluence",
+      "Make a dashboard of this sprint's test results",
+      "Add the last screenshot of that run to ADO 256 as a comment",
+      "Run the GitHub issues labelled login as test cases",
+    ],
     requires: [{ kind: "system", anyOf: ["azure_devops", "jira", "xray", "confluence"] }],
     docs: [{ doc: "README.md", heading: "Azure DevOps, Jira, and other systems" }],
   },

package/src/cases/bugs.ts

@@ -6,6 +6,9 @@ import type { BugsConfig, SourcesConfig } from "../config.ts"
 import { browserErrors, problemLine } from "../report/data.ts"
 import { ciInfo } from "../report/html.ts"
 import { adoSettings } from "./ado.ts"
+import { DefectBook, type CaseDefect, type DefectCluster } from "./defects.ts"
+import { rcaLines, reproPack, reproText } from "./repro.ts"
+import { githubBugTracker } from "./github.ts"
 import { http, textToAdf } from "./http.ts"
 import { jiraApi, type JiraApi } from "./jira.ts"
 import { stepVerdictLines, type CaseResult, type WriteBack } from "./types.ts"
@@ -57,35 +60,82 @@ export function bugText(r: CaseResult, runName: string): string {
 const failing = (r: CaseResult, b: BugsConfig) =>
   r.failure ? r.failure.type === "functional_defect" : r.status === "failed" || (b.onError && r.status === "error")
 
-/** File a bug for each failing case, or comment on the open one filed before; note on the open bug when a case passes again. */
-export async function fileBugs(results: CaseResult[], cfg: SourcesConfig, runName: string): Promise<WriteBack[]> {
+/** A defect from browser evidence holds across runs and cases; a "page" defect (the agent's words) only within a run. */
+const lasting = (d?: CaseDefect): d is CaseDefect => !!d && d.kind !== "page"
+
+/** The bug's title: the defect, when cases share it by evidence; else the case. */
+export function defectBugTitle(r: CaseResult, d?: CaseDefect): string {
+  return lasting(d) ? `[ForgeQE] ${d.title}`.slice(0, 250) : bugTitle(r)
+}
+
+/**
+ * The bug's description: the defect's evidence first when it has some, then the case that found it, then how to make
+ * it happen again (src/cases/repro.ts) when the defect is known.
+ */
+export function defectBugText(r: CaseResult, runName: string, d?: CaseDefect, book?: DefectBook): string {
+  const repro = d ? ["", reproText(reproPack(r, d, { env: book?.env, seen: book?.past[d.id]?.seen ?? book?.earlier?.(r.case.id) }))] : []
+  if (!lasting(d)) return [bugText(r, runName), ...repro].join("\n")
+  return [`Defect: ${d.title}`, ...d.evidence.map((e) => `- ${e}`), "", "Every test case that fails this way is added to this bug as a comment.", "", "First found by:", bugText(r, runName), ...repro].join("\n")
+}
+
+/**
+ * The root-cause analysis of each defect added to its bug as a comment, once the suite has it. Only bugs filed or
+ * found in this run, and only analyses with a hypothesis.
+ */
+export async function commentAnalyses(cfg: SourcesConfig, book: DefectBook, clusters: DefectCluster[]): Promise<WriteBack[]> {
+  const b = cfg.bugs
+  const todo = clusters.filter((c) => c.rca?.hypothesis && book.bugs.has(c.id))
+  if (!b || !todo.length) return []
+  let tracker: Tracker
+  try {
+    tracker = b.system === "jira" ? jiraTracker(cfg, b) : b.system === "github" ? githubBugTracker(cfg, b) : adoTracker(cfg, b)
+  } catch (err) {
+    return [{ source: "bugs", text: "Analyses not added to bugs", error: (err as Error).message }]
+  }
+  const out: WriteBack[] = []
+  for (const c of todo) {
+    const bug = book.bugs.get(c.id)!
+    try {
+      await tracker.comment(bug.id, ["Root-cause analysis by ForgeQE: a hypothesis to check, not a verdict.", "", ...rcaLines(c.rca!)].join("\n"))
+      out.push({ source: "bugs", caseId: bug.caseId, text: `${bug.label}: root-cause analysis added`, url: bug.url })
+    } catch (err) {
+      out.push({ source: "bugs", caseId: bug.caseId, text: `${bug.label}: analysis not added`, error: (err as Error).message })
+    }
+  }
+  return out
+}
+
+/**
+ * File a bug for each defect (cases failing the same way share one: src/cases/defects.ts), or for each failing case
+ * when bugs.group_by is case. A case joining a defect's bug is added as a comment and tagged with its own fingerprint,
+ * so the note when it passes again finds that bug. Notes on the open bug when a case passes again.
+ */
+export async function fileBugs(results: CaseResult[], cfg: SourcesConfig, runName: string, book = new DefectBook()): Promise<WriteBack[]> {
   const b = cfg.bugs
   if (!b) return []
   const relevant = results.filter((r) => failing(r, b) || r.status === "passed")
   if (!relevant.length) return []
   let tracker: Tracker
   try {
-    tracker = b.system === "jira" ? jiraTracker(cfg, b) : adoTracker(cfg, b)
+    tracker = b.system === "jira" ? jiraTracker(cfg, b) : b.system === "github" ? githubBugTracker(cfg, b) : adoTracker(cfg, b)
   } catch (err) {
     return [{ source: "bugs", text: "Bugs not filed", error: (err as Error).message }]
   }
   const out: WriteBack[] = []
   for (const r of relevant) {
     const fp = bugFingerprint(r)
+    // A bug filed before ForgeQE was renamed from WebPilot carries the same hash under the old prefix.
+    const byCase = async () => (await tracker.findOpen(fp)) ?? (await tracker.findOpen(fp.replace(/^forgeqe-/, "webpilot-")))
     try {
-      // A bug filed before ForgeQE was renamed from WebPilot carries the same hash under the old prefix.
-      const open = (await tracker.findOpen(fp)) ?? (await tracker.findOpen(fp.replace(/^forgeqe-/, "webpilot-")))
       if (r.status === "passed") {
+        const open = await byCase()
         if (!open) continue
         await tracker.comment(open.id, `ForgeQE: ${r.case.id} passed again in "${runName}".`)
         out.push({ source: "bugs", caseId: r.case.id, text: `${open.label}: noted that ${r.case.id} passes again`, url: open.url })
-      } else if (open) {
-        await tracker.comment(open.id, `Still failing.\n\n${bugText(r, runName)}`)
-        out.push({ source: "bugs", caseId: r.case.id, text: `${open.label}: still failing, comment added`, url: open.url })
-      } else {
-        const bug = await tracker.create(r, fp, runName)
-        out.push({ source: "bugs", caseId: r.case.id, text: `${bug.label}: bug filed for ${r.case.id}${bug.note ? ` (${bug.note})` : ""}`, url: bug.url })
+        continue
       }
+      const d = b.groupBy === "case" ? undefined : (r.defect ?? book.assign(r))
+      out.push(await book.serial(() => fileOne(tracker, b, r, fp, d, runName, book, byCase)))
     } catch (err) {
       out.push({ source: "bugs", caseId: r.case.id, text: `${r.case.id}: bug not filed`, error: (err as Error).message })
     }
@@ -93,12 +143,91 @@ export async function fileBugs(results: CaseResult[], cfg: SourcesConfig, runNam
   return out
 }
 
-type BugRef = { id: string; label: string; url: string; note?: string }
+async function fileOne(tracker: Tracker, b: BugsConfig, r: CaseResult, fp: string, d: CaseDefect | undefined, runName: string, book: DefectBook, byCase: () => Promise<BugRef | null>): Promise<WriteBack> {
+  const id = r.case.id
+  // Another case of this defect filed or found its bug earlier in the run: this case joins it.
+  const shared = d && book.bugs.get(d.id)
+  if (shared) {
+    await tracker.comment(shared.id, `Also fails: ${id}.\n\n${bugText(r, runName)}`)
+    const tagged = await tag(tracker, shared.id, fp)
+    return { source: "bugs", caseId: id, text: `${shared.label}: same defect as ${shared.caseId}, ${id} added${tagged}`, url: shared.url }
+  }
+  const byDefect = lasting(d) ? await tracker.findOpen(d.id) : null
+  const open = byDefect ?? (await byCase())
+  const gone = d && book.past[d.id]?.goneSince
+  if (open) {
+    const head = gone ? `Failing again after it went away on ${gone.slice(0, 10)}` : "Still failing"
+    await tracker.comment(open.id, `${head}${byDefect ? `: ${id}` : ""}.\n\n${bugText(r, runName)}`)
+    // Found by one fingerprint, it gets the other, so the next run finds it either way.
+    const tagged = await tag(tracker, open.id, byDefect ? fp : lasting(d) ? d.id : "")
+    if (d) book.bugs.set(d.id, { ...open, caseId: id })
+    return { source: "bugs", caseId: id, text: `${open.label}: still failing, comment added${tagged}`, url: open.url }
+  }
+  // No open bug: a closed one with either fingerprint means it was fixed and came back.
+  const closed = (lasting(d) ? await tracker.findClosed(d.id) : null) ?? (await tracker.findClosed(fp))
+  const labels = [...new Set([...b.labels, ...(lasting(d) ? [d.id] : []), fp])]
+  if (closed) {
+    const when = closed.closedAt ? ` on ${closed.closedAt.slice(0, 10)}` : ""
+    const body = [`Regression: this came back. ${closed.label} (${closed.url}) was closed${when}.`, "", defectBugText(r, runName, d, book)].join("\n")
+    const bug = await tracker.create(r, { title: `[ForgeQE] Regression: ${defectBugTitle(r, d).replace(/^\[ForgeQE\] /, "")}`.slice(0, 250), body, labels, regressionOf: closed }, runName)
+    if (d) {
+      book.bugs.set(d.id, { ...bug, caseId: id })
+      book.closed.set(d.id, { label: closed.label, url: closed.url, ...(closed.closedAt ? { closedAt: closed.closedAt } : {}) })
+    }
+    return { source: "bugs", caseId: id, text: `${bug.label}: regression of ${closed.label}, bug filed for ${id}${bug.note ? ` (${bug.note})` : ""}`, url: bug.url }
+  }
+  // Bugs people filed by hand about the same route or error: named on the new bug, never merged.
+  const related = lasting(d) && d.term ? await relatedBugs(tracker, d.term) : []
+  const body = defectBugText(r, runName, d, book) + (related.length ? `\n\nPossibly related open bugs (they mention ${d!.term}):\n${related.map((x) => `- ${x.label}: ${x.title} (${x.url})`).join("\n")}` : "")
+  const bug = await tracker.create(r, { title: defectBugTitle(r, d), body, labels }, runName)
+  if (d) {
+    book.bugs.set(d.id, { ...bug, caseId: id })
+    if (related.length) book.related.set(d.id, related.map((x) => ({ label: x.label, url: x.url, title: x.title })))
+  }
+  const also = related.length ? `, ${related.length} possibly related` : ""
+  return { source: "bugs", caseId: id, text: `${bug.label}: bug filed for ${id}${bug.note || also ? ` (${[bug.note, also.slice(2)].filter(Boolean).join(", ")})` : ""}`, url: bug.url }
+}
+
+/** The search for related bugs is a hint: a tracker that cannot run it files the bug without one. */
+async function relatedBugs(tracker: Tracker, term: string): Promise<FoundBug[]> {
+  try {
+    return (await tracker.related(term, 3)).filter((x) => !/^\[(ForgeQE|WebPilot)\]/.test(x.title))
+  } catch {
+    return []
+  }
+}
+
+/** Add a label or tag; a tracker that refuses only loses the note, not the comment. */
+async function tag(tracker: Tracker, id: string, label: string): Promise<string> {
+  if (!label) return ""
+  try {
+    await tracker.tag(id, label)
+    return ""
+  } catch {
+    return ` (not tagged ${label})`
+  }
+}
 
-type Tracker = {
+export type BugRef = { id: string; label: string; url: string; note?: string }
+
+/** A closed bug, and when it was closed when the tracker says. */
+export type ClosedBug = BugRef & { closedAt?: string }
+
+/** An open bug found by its text, with its title. */
+export type FoundBug = BugRef & { title: string }
+
+/** The bug's title, description, and labels (or tags): its fingerprints among them. `regressionOf`: the closed bug it came back from, linked. */
+export type NewBug = { title: string; body: string; labels: string[]; regressionOf?: ClosedBug }
+
+export type Tracker = {
   findOpen(fingerprint: string): Promise<BugRef | null>
-  create(r: CaseResult, fingerprint: string, runName: string): Promise<BugRef>
+  /** The most recently closed bug with this label or tag. */
+  findClosed(fingerprint: string): Promise<ClosedBug | null>
+  /** Open bugs whose text mentions `term`, newest first. */
+  related(term: string, limit: number): Promise<FoundBug[]>
+  create(r: CaseResult, bug: NewBug, runName: string): Promise<BugRef>
   comment(id: string, text: string): Promise<void>
+  tag(id: string, label: string): Promise<void>
 }
 
 function screenshot(r: CaseResult): { name: string; data: Buffer } | null {
@@ -120,16 +249,29 @@ function jiraTracker(cfg: SourcesConfig, b: BugsConfig): Tracker {
       const hit = data?.issues?.[0]
       return hit ? ref(hit.key) : null
     },
-    async create(r, fp, runName) {
+    async findClosed(fp) {
+      const jql = `project = "${b.project}" AND labels = "${fp}" AND statusCategory = Done ORDER BY updated DESC`
+      const q = new URLSearchParams({ jql, fields: "summary,resolutiondate", maxResults: "1" })
+      const { data } = await http<{ issues?: { key: string; fields?: { resolutiondate?: string | null } }[] }>(`${j.api}/${j.cloud ? "search/jql" : "search"}?${q}`, { auth: j.auth })
+      const hit = data?.issues?.[0]
+      return hit ? { ...ref(hit.key), ...(hit.fields?.resolutiondate ? { closedAt: hit.fields.resolutiondate } : {}) } : null
+    },
+    async related(term, limit) {
+      const jql = `project = "${b.project}" AND statusCategory != Done AND text ~ "\\"${term.replace(/["\\]/g, " ")}\\"" ORDER BY updated DESC`
+      const q = new URLSearchParams({ jql, fields: "summary", maxResults: String(limit) })
+      const { data } = await http<{ issues?: { key: string; fields?: { summary?: string } }[] }>(`${j.api}/${j.cloud ? "search/jql" : "search"}?${q}`, { auth: j.auth })
+      return (data?.issues || []).map((i) => ({ ...ref(i.key), title: i.fields?.summary || "" }))
+    },
+    async create(r, bug) {
       const { data } = await http<{ key: string; id: string }>(`${j.api}/issue`, {
         auth: j.auth,
         body: {
           fields: {
             project: { key: b.project },
             issuetype: { name: b.type },
-            summary: bugTitle(r),
-            description: body(bugText(r, runName)),
-            labels: [...new Set([...b.labels, fp])],
+            summary: bug.title,
+            description: body(bug.body),
+            labels: bug.labels,
           },
         },
       })
@@ -145,6 +287,14 @@ function jiraTracker(cfg: SourcesConfig, b: BugsConfig): Tracker {
         })
         notes.push(res.ok ? "screenshot attached" : `screenshot not attached: ${res.status}`)
       }
+      if (bug.regressionOf) {
+        try {
+          await http(`${j.api}/issueLink`, { auth: j.auth, body: { type: { name: "Relates" }, inwardIssue: { key: data.key }, outwardIssue: { key: bug.regressionOf.id } } })
+          notes.push(`linked to ${bug.regressionOf.label}`)
+        } catch {
+          notes.push(`not linked to ${bug.regressionOf.label}`)
+        }
+      }
       const linked = r.case.source === "jira" || r.case.source === "xray" ? String(r.case.ref?.issue || r.case.ref?.test || r.case.id) : ""
       if (linked) {
         try {
@@ -159,6 +309,9 @@ function jiraTracker(cfg: SourcesConfig, b: BugsConfig): Tracker {
     async comment(id, text) {
       await http(`${j.api}/issue/${encodeURIComponent(id)}/comment`, { auth: j.auth, body: { body: body(text) } })
     },
+    async tag(id, label) {
+      await http(`${j.api}/issue/${encodeURIComponent(id)}`, { method: "PUT", auth: j.auth, body: { update: { labels: [{ add: label }] } } })
+    },
   }
 }
 
@@ -181,12 +334,35 @@ function adoTracker(cfg: SourcesConfig, b: BugsConfig): Tracker {
       const hit = data?.workItems?.[0]
       return hit ? ref(hit.id) : null
     },
-    async create(r, fp, runName) {
+    async findClosed(fp) {
+      const query =
+        `SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project AND [System.WorkItemType] = '${b.type.replace(/'/g, "''")}' ` +
+        `AND [System.Tags] CONTAINS '${fp}' AND [System.State] IN ('Closed', 'Done', 'Resolved') ORDER BY [System.ChangedDate] DESC`
+      const { data } = await http<{ workItems?: { id: number }[] }>(`${base}/_apis/wit/wiql?${api}&$top=1`, { auth, body: { query } })
+      const hit = data?.workItems?.[0]
+      if (!hit) return null
+      // Items created closed (or moved there by a rule) have no ClosedDate: when their state last changed is when they closed.
+      const dates = ["Microsoft.VSTS.Common.ClosedDate", "Microsoft.VSTS.Common.ResolvedDate", "Microsoft.VSTS.Common.StateChangeDate"]
+      const { data: item } = await http<{ fields?: Record<string, string> }>(`${base}/_apis/wit/workitems/${hit.id}?fields=${dates.join(",")}&${api}`, { auth })
+      const at = dates.map((f) => item?.fields?.[f]).find(Boolean)
+      return { ...ref(hit.id), ...(at ? { closedAt: at } : {}) }
+    },
+    async related(term, limit) {
+      const query =
+        `SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project AND [System.WorkItemType] = '${b.type.replace(/'/g, "''")}' ` +
+        `AND [System.State] NOT IN ('Closed', 'Done', 'Removed', 'Resolved') AND ([System.Title] CONTAINS '${term.replace(/'/g, "''")}' OR [Microsoft.VSTS.TCM.ReproSteps] CONTAINS WORDS '${term.replace(/'/g, "''")}') ORDER BY [System.ChangedDate] DESC`
+      const { data } = await http<{ workItems?: { id: number }[] }>(`${base}/_apis/wit/wiql?${api}&$top=${limit}`, { auth, body: { query } })
+      const ids = (data?.workItems || []).slice(0, limit).map((w) => w.id)
+      if (!ids.length) return []
+      const { data: items } = await http<{ value?: { id: number; fields?: Record<string, string> }[] }>(`${base}/_apis/wit/workitems?ids=${ids.join(",")}&fields=System.Title&${api}`, { auth })
+      return (items?.value || []).map((w) => ({ ...ref(w.id), title: w.fields?.["System.Title"] || "" }))
+    },
+    async create(r, bug) {
       const notes: string[] = []
       const ops: Record<string, unknown>[] = [
-        { op: "add", path: "/fields/System.Title", value: bugTitle(r) },
-        { op: "add", path: "/fields/Microsoft.VSTS.TCM.ReproSteps", value: html(bugText(r, runName)) },
-        { op: "add", path: "/fields/System.Tags", value: [...new Set([...b.labels, fp])].join("; ") },
+        { op: "add", path: "/fields/System.Title", value: bug.title },
+        { op: "add", path: "/fields/Microsoft.VSTS.TCM.ReproSteps", value: html(bug.body) },
+        { op: "add", path: "/fields/System.Tags", value: bug.labels.join("; ") },
       ]
       if (b.areaPath) ops.push({ op: "add", path: "/fields/System.AreaPath", value: b.areaPath })
       const testCase = r.case.source === "ado" ? Number(r.case.ref?.workItem) : 0
@@ -194,6 +370,10 @@ function adoTracker(cfg: SourcesConfig, b: BugsConfig): Tracker {
         ops.push({ op: "add", path: "/relations/-", value: { rel: "Microsoft.VSTS.Common.TestedBy-Forward", url: `${ado.orgUrl}/_apis/wit/workItems/${testCase}` } })
         notes.push(`linked to test case ${testCase}`)
       }
+      if (bug.regressionOf) {
+        ops.push({ op: "add", path: "/relations/-", value: { rel: "System.LinkTypes.Related", url: `${ado.orgUrl}/_apis/wit/workItems/${bug.regressionOf.id}`, attributes: { comment: "Regression of" } } })
+        notes.push(`linked to ${bug.regressionOf.label}`)
+      }
       const shot = screenshot(r)
       if (shot) {
         const res = await fetch(`${base}/_apis/wit/attachments?fileName=${encodeURIComponent(shot.name)}&${api}`, {
@@ -219,5 +399,12 @@ function adoTracker(cfg: SourcesConfig, b: BugsConfig): Tracker {
     async comment(id, text) {
       await http(`${base}/_apis/wit/workItems/${id}/comments?api-version=7.1-preview.4`, { auth, body: { text: html(text) } })
     },
+    async tag(id, label) {
+      // Setting System.Tags replaces them all: read the ones it has first.
+      const { data } = await http<{ fields?: Record<string, string> }>(`${base}/_apis/wit/workitems/${id}?fields=System.Tags&${api}`, { auth })
+      const tags = (data?.fields?.["System.Tags"] || "").split(";").map((t) => t.trim()).filter(Boolean)
+      if (tags.includes(label)) return
+      await http(`${base}/_apis/wit/workitems/${id}?${api}`, { method: "PATCH", auth, contentType: "application/json-patch+json", body: [{ op: "add", path: "/fields/System.Tags", value: [...tags, label].join("; ") }] })
+    },
   }
 }