@capagents/forgeqe 1.2.0 → 1.3.0

package/src/mcp/packtools.ts

@@ -0,0 +1,187 @@
+import { realpathSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { listPacks, loadPack, makePack, packCard, packMarkdown, packRunCard, runPack, type PackSources } from "../pack/index.ts"
+import { packsDir } from "../pack/pack.ts"
+import { runPackOnPipeline } from "../pack/pipeline.ts"
+import type { McpTool, ToolContext } from "./tools.ts"
+
+const clip = (s: string | undefined, n: number) => {
+  const t = (s || "").trim()
+  return t.length <= n ? t : `…${t.slice(-(n - 1))}`
+}
+
+function repoOf(ctx: ToolContext, given?: unknown): string {
+  const p = given ? path.resolve(ctx.cwd, String(given)) : ctx.cwd
+  try {
+    return realpathSync(p)
+  } catch {
+    return p
+  }
+}
+
+const ITEM_SCHEMA = {
+  type: "object",
+  properties: {
+    source: { type: "string", description: "The tool it came from: jira, github, azure_devops, confluence, linear…" },
+    id: { type: "string" },
+    title: { type: "string" },
+    text: { type: "string", description: "What changes, in its words: description, acceptance criteria, release note" },
+    url: { type: "string" },
+    type: { type: "string", description: "Story, Bug, Feature, Task…" },
+    kind: { type: "string", enum: ["work_item", "pr", "commit", "note"] },
+    files: { type: "array", items: { type: "string" }, description: "Files it changed, when known" },
+    links: { type: "array", items: { type: "string" }, description: "Work items it refers to: ado:123, jira:PAY-12, github:45" },
+    test_cases: { type: "array", items: { type: "string" }, description: "Test cases that test it (Azure DevOps ids, or ADO-123)" },
+  },
+  required: ["title"],
+}
+
+export const PACK_TOOLS: McpTool[] = [
+  {
+    name: "build_regression_pack",
+    description:
+      "Build a regression pack: the repository's tests that a release's changes can break, each with why it is in (it automates a test case of a changed work item; the change is in the test code it uses; the work item's words match what it does; it works in a risk area the release touches; it is a smoke test), and the changes no test covers, each with the closest test and what it lacks. Changes come from any mix of: an Azure DevOps sprint, area, epic, or work item ids (with their linked pull requests' files); the commits between two refs of a repository; pull requests by number or merged in the last days; and items you read from any other connected tool (Jira, GitHub issues, a release note), passed in items. Saves the pack by name in .forgeqe/packs and shows a card. Nothing runs. Takes seconds.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "The pack's name, e.g. release-1.5 (default: release-<date>)" },
+        repo: { type: "string", description: "The test repository (default: the working directory)" },
+        sprint: { type: "string", description: "Azure DevOps sprint name of the team, or current" },
+        iteration: { type: "string", description: "Azure DevOps iteration path and everything under it: a release such as Release 2026.09, or Project\\Release 2026.09\\Sprint 13" },
+        area: { type: "string", description: "Azure DevOps area path" },
+        parent: { type: "number", description: "An Azure DevOps epic or feature: everything under it" },
+        work_items: { type: "array", items: { type: "number" }, description: "Azure DevOps work item ids" },
+        project: { type: "string", description: "Azure DevOps project (default: sources.azure_devops.project)" },
+        range_repo: { type: "string", description: "Repository for from/to (the product's, or the tests' own); default: the test repository" },
+        from: { type: "string", description: "Commits after this ref: a tag, branch, or commit (e.g. release/1.4)" },
+        to: { type: "string", description: "Commits up to this ref (default HEAD)" },
+        prs: { type: "array", items: { type: "string" }, description: "Pull request numbers or URLs" },
+        merged_days: { type: "number", description: "Pull requests merged in the last N days" },
+        pr_repo: { type: "string", description: "Repository the pull requests are in (default: the test repository)" },
+        items: { type: "array", items: ITEM_SCHEMA, description: "Changes you read from other connected tools, as they are" },
+        risk: { type: "boolean", description: "Add tests for risk areas the release touches (default true)" },
+        smoke: { type: "boolean", description: "Add smoke-tagged tests (default true)" },
+      },
+    },
+    async run(args, ctx) {
+      const repo = repoOf(ctx, args.repo)
+      const sources: PackSources = {
+        ...(args.sprint || args.iteration || args.area || args.parent || (Array.isArray(args.work_items) && args.work_items.length)
+          ? { ado: { ...(args.sprint ? { sprint: String(args.sprint) } : {}), ...(args.iteration ? { iteration: String(args.iteration) } : {}), ...(args.area ? { area: String(args.area) } : {}), ...(args.parent ? { parent: Number(args.parent) } : {}), ...(Array.isArray(args.work_items) ? { ids: args.work_items.map(Number).filter(Boolean) } : {}), ...(args.project ? { project: String(args.project) } : {}) } }
+          : {}),
+        ...(args.from ? { range: { repo: repoOf(ctx, args.range_repo || args.repo), from: String(args.from), ...(args.to ? { to: String(args.to) } : {}) } } : {}),
+        ...(Array.isArray(args.prs) && args.prs.length ? { prs: args.prs.map(String) } : {}),
+        ...(Number(args.merged_days) > 0 ? { mergedDays: Number(args.merged_days) } : {}),
+        ...(args.pr_repo ? { prRepo: repoOf(ctx, args.pr_repo) } : {}),
+        ...(Array.isArray(args.items) && args.items.length ? { items: args.items } : {}),
+      }
+      const pack = await makePack({ config: ctx.config, repo, name: args.name ? String(args.name) : undefined, sources, risk: args.risk !== false, smoke: args.smoke !== false })
+      const md = path.join(packsDir(repo), `${pack.name}.md`)
+      writeFileSync(md, `${packMarkdown(pack)}\n`)
+      ctx.emit?.({ type: "card", card: packCard(pack) })
+      return {
+        name: pack.name,
+        tests: pack.tests.map((t) => ({ test: t.test, file: t.file, why: [...new Set(t.reasons.map((r) => r.text))], ...(t.flaky ? { flaky: t.flaky } : {}) })),
+        changes: pack.items.length,
+        from: pack.scope,
+        not_covered: pack.uncovered,
+        risk_areas: pack.risk,
+        notes: pack.notes.length ? pack.notes : undefined,
+        file: md,
+        next_step: [
+          pack.tests.length ? `Offer to run it: run_regression_pack with name ${pack.name} and on local, testmu, or pipeline.` : "",
+          pack.uncovered.length ? "Name the changes no test covers. For one with a closest test, offer to extend that test (browser_run with existing_test and existing_mode extend), so the next pack covers it." : "",
+        ]
+          .filter(Boolean)
+          .join(" "),
+      }
+    },
+  },
+  {
+    name: "run_regression_pack",
+    description:
+      "Run a saved regression pack after the user confirms: on local (this machine's browsers), testmu (TestMu AI's cloud browsers: the repository's tests connect to them through FORGEQE_PW_WS_ENDPOINT), or pipeline (a CI pipeline runs it). Reads each test's result, keeps the run with the pack, and says what changed since its last run. Where ForgeQE cannot ask (an MCP client), pass confirmed: true only after the user agreed. Takes minutes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "The pack's name" },
+        on: { type: "string", enum: ["local", "testmu", "pipeline"], description: "Where to run it (default local)" },
+        pipeline: { type: "string", enum: ["github", "azure_devops"], description: "With on pipeline: which one (default: packs.pipeline.default in forgeqe.yaml)" },
+        browsers: { type: "string", enum: ["local", "testmu"], description: "With on pipeline: the runner's own browser, or TestMu AI's (default local)" },
+        repo: { type: "string", description: "The test repository (default: the working directory)" },
+        confirmed: { type: "boolean", description: "Only where ForgeQE cannot ask: the user agreed to this run" },
+      },
+      required: ["name"],
+    },
+    async run(args, ctx) {
+      const repo = repoOf(ctx, args.repo)
+      const pack = loadPack(repo, String(args.name))
+      const on = args.on === "testmu" || args.on === "pipeline" ? args.on : "local"
+      const browsers = args.browsers === "testmu" ? "testmu" : "local"
+      const where = on === "testmu" ? "on TestMu AI" : on === "pipeline" ? `in the ${args.pipeline === "azure_devops" ? "Azure DevOps" : args.pipeline === "github" ? "GitHub Actions" : "configured"} pipeline${browsers === "testmu" ? " on TestMu AI" : ""}` : "on this machine"
+      const what = `${pack.tests.length} test${pack.tests.length === 1 ? "" : "s"}`
+      if (ctx.ask) {
+        const choice = await ctx.ask({
+          title: `Run pack ${pack.name} (${what}) ${where}?`,
+          lines: pack.tests.slice(0, 20).map((t) => `  • ${t.test}`).concat(pack.tests.length > 20 ? [`  and ${pack.tests.length - 20} more`] : []),
+          options: [
+            { id: "run", label: `Run ${what} ${where}` },
+            { id: "no", label: "Don't run" },
+          ],
+        })
+        if (choice !== "run") return { ran: false, reason: "The user chose not to run it." }
+      } else if (args.confirmed !== true) {
+        return { ran: false, needs_confirmation: true, tests: pack.tests.map((t) => t.test), on, next_step: "Show the user the pack and where it runs; call run_regression_pack again with confirmed: true only after they say yes." }
+      }
+      const { run, record, notes, pack: after } =
+        on === "pipeline"
+          ? await runPackOnPipeline({
+              config: ctx.config,
+              repo,
+              name: pack.name,
+              ...(args.pipeline === "github" || args.pipeline === "azure_devops" ? { kind: args.pipeline } : {}),
+              target: browsers,
+              signal: ctx.signal,
+              onProgress: (text) => ctx.emit?.({ type: "agent", event: { type: "code", kind: "info", text } }),
+            })
+          : await runPack({ config: ctx.config, repo, name: pack.name, on, signal: ctx.signal, runTest: ctx.runTest })
+      ctx.emit?.({ type: "card", card: packRunCard(after, run, record, notes) })
+      const failed = run.tests.filter((t) => t.status === "failed")
+      return {
+        ran: true,
+        on: record.target,
+        status: run.status,
+        passed: run.counts.passed,
+        failed: run.counts.failed,
+        skipped: run.counts.skipped,
+        seconds: run.seconds,
+        failures: failed.length ? failed.map((t) => ({ name: t.name, message: t.message })) : undefined,
+        ...(run.flaky?.length ? { flaky: run.flaky } : {}),
+        previous: after.runs.at(-2) || undefined,
+        output: run.status === "passed" ? undefined : clip(run.output, 3000),
+        folder: run.dir,
+        ...(record.url ? { pipeline_run: record.url } : {}),
+        notes: notes.length ? notes : undefined,
+        next_step: failed.length ? "Name the failing tests with their messages; offer heal_tests for a test the app outgrew, or file the defects (file_bug)." : undefined,
+      }
+    },
+  },
+  {
+    name: "list_regression_packs",
+    description: "The saved regression packs of a repository: name, when built, from what, how many tests and gaps, and their last run. Nothing runs.",
+    inputSchema: { type: "object", properties: { repo: { type: "string" } } },
+    async run(args, ctx) {
+      return {
+        packs: listPacks(repoOf(ctx, args.repo)).map((p) => ({
+          name: p.name,
+          built: p.createdAt.slice(0, 16).replace("T", " "),
+          from: p.scope,
+          tests: p.tests.length,
+          not_covered: p.uncovered.length,
+          last_run: p.runs.at(-1) ? { at: p.runs.at(-1)!.at.slice(0, 16).replace("T", " "), on: p.runs.at(-1)!.target, status: p.runs.at(-1)!.status, failed: p.runs.at(-1)!.counts.failed } : undefined,
+        })),
+      }
+    },
+  },
+]

package/src/mcp/tools.ts

@@ -11,14 +11,18 @@ import { createAdoDashboard, type DashboardWidget } from "../cases/dashboards.ts
 import { writeAdoWikiPage } from "../cases/wiki.ts"
 import { readConfluence } from "../cases/confluence.ts"
 import { casesFrom, type CaseSelector, type TestCase } from "../cases/index.ts"
-import { saveAdoCases, saveJiraCases, type NewCase } from "../cases/save.ts"
+import { saveAdoCases, saveJiraCases, type NewCase, type SaveStatus } from "../cases/save.ts"
 import { buildHandoff } from "../code/handoff.ts"
 import { latestRunDir, runCodeAgent } from "../code/index.ts"
 import type { OpencodeSession } from "../code/runtime.ts"
 import { runTestCommand } from "../code/testrun.ts"
-import { EXISTING_TEST_FILE, findWrittenTest } from "../code/notes.ts"
+import { EXISTING_TEST_FILE, EXTEND_TEST_FILE, findRelatedTests, findWrittenTest, sameFlow, writtenTestFor, writtenTests } from "../code/notes.ts"
+import { buildGraph } from "../code/graph/graph.ts"
+import { walk } from "../code/profile.ts"
+import { indexTests, oneTestCommand, shortlistTests } from "../code/shortlist.ts"
+import { recordDecision } from "../code/decisions.ts"
 import { browserProvider, type AppConfig } from "../config.ts"
-import { clearMemory, memoryFilesFor, memoryFlows, memoryOverview, memoryShow } from "../memory.ts"
+import { clearMemory, memoryFilesFor, memoryFlows, memoryOverview, memoryShow, readPages } from "../memory.ts"
 import { executeRun, runDirectory } from "../run.ts"
 import { counts } from "../suite/report.ts"
 import { deviceCases, runSuite, suiteParallel, type SuiteEvent, type SuiteResult } from "../suite/run.ts"
@@ -27,6 +31,7 @@ import { PR_TOOLS } from "./prtools.ts"
 import { CASE_TOOLS, checkResult, precheck } from "./casetools.ts"
 import { REPO_TEST_TOOLS } from "./repotests.ts"
 import { DEFECT_TOOLS } from "./defecttools.ts"
+import { PACK_TOOLS } from "./packtools.ts"
 import { API_TOOLS } from "./apitools.ts"
 import { EXPLORE_TOOLS } from "./exploretools.ts"
 import { QUALITY_TOOLS } from "./qualitytools.ts"
@@ -330,21 +335,42 @@ function devicesFor(args: Record<string, unknown>, ctx: ToolContext): string[] {
   return [...new Set(devices)]
 }
 
+type ExistingFirst = { passed?: Record<string, unknown>; failed?: { testFile: string; command: string; output: string; why: string } }
+
+function repoOf(ctx: ToolContext): string {
+  try {
+    return realpathSync(ctx.cwd)
+  } catch {
+    return ctx.cwd
+  }
+}
+
 /**
  * Runs the test an earlier job wrote for this goal, if there is one. `passed`: the tool's answer, the test having
  * passed in a browser. `failed`: the test to update, for write_test. Null when there is no such test.
  */
-async function existingTestFirst(goal: string, runDir: string, ctx: ToolContext): Promise<{ passed?: Record<string, unknown>; failed?: { testFile: string; command: string; output: string; why: string } } | null> {
+async function existingTestFirst(goal: string, runDir: string, ctx: ToolContext): Promise<ExistingFirst | null> {
   const cfg = ctx.config
   if (!cfg.memory.enabled) return null
-  let repo = ctx.cwd
-  try {
-    repo = realpathSync(ctx.cwd)
-  } catch {}
+  const repo = repoOf(ctx)
   const known = findWrittenTest(cfg.memory.dir, repo, goal, (f) => existsSync(path.resolve(repo, f)))
   if (!known) return null
+  ctx.emit?.({ type: "info", text: `This flow already has a test, ${known.test_file} (written ${known.at.slice(0, 10)}): ForgeQE runs it first` })
+  recordDecision(repo, { goal, stage: "chosen", where: "browser_run", by: "history", mode: "reuse", file: known.test_file, why: `an earlier job wrote it for the same flow (${known.at.slice(0, 10)})` })
+  return runKnownTest(known, repo, runDir, ctx, goal)
+}
+
+/** A test to run as it is: one an earlier job wrote (with the goal it was written for), or one found in the repository. */
+type RunnableTest = { test_file: string; command: string; test?: string; goal?: string; at?: string; derived?: boolean }
+
+/**
+ * Runs an existing test as it is: passing in a browser answers the goal; failing, Scribe updates it after the run.
+ * A command ForgeQE built itself (derived) that opens no browser ran nothing: the browser runs, and nothing is updated.
+ */
+async function runKnownTest(known: RunnableTest, repo: string, runDir: string, ctx: ToolContext, goal: string, asCheck = false): Promise<ExistingFirst | null> {
+  const outcome = (status: string) => recordDecision(repo, { goal, stage: "outcome", where: "browser_run", mode: "reuse", file: known.test_file, ...(known.test ? { test: known.test } : {}), status, run_dir: runDir })
+  const cfg = ctx.config
   const emit = ctx.emit || (() => {})
-  emit({ type: "info", text: `This flow already has a test, ${known.test_file} (written ${known.at.slice(0, 10)}): ForgeQE runs it first` })
   mkdirSync(runDir, { recursive: true })
   const run = await (ctx.runTest || runTestCommand)({
     command: known.command,
@@ -356,33 +382,151 @@ async function existingTestFirst(goal: string, runDir: string, ctx: ToolContext)
   })
   if (ctx.signal?.aborted) return null
   const secs = Math.round(run.ms / 1000)
+  const name = known.test ? `${known.test} (${known.test_file})` : known.test_file
   if (run.ok && run.browsers.length) {
+    outcome("passed")
     emit({
       type: "card",
       card: {
         status: "ok",
         title: "Existing test passed",
         stats: `${secs}s · no browser run or new test needed`,
-        body: [`Test      ${known.test_file}`, `Command   ${known.command}`, `Browser   ${run.browsers.join(", ")}`, `Written   ${known.at.slice(0, 10)} for the same flow`],
+        body: [`Test      ${name}`, `Command   ${known.command}`, `Browser   ${run.browsers.join(", ")}`, ...(known.at ? [`Written   ${known.at.slice(0, 10)} by an earlier job`] : [])],
       },
     })
     return {
       passed: {
         status: "passed",
         reused_test: known.test_file,
-        written_for: known.goal,
+        ...(known.test ? { test: known.test } : {}),
+        ...(known.goal ? { written_for: known.goal } : {}),
         command: known.command,
         browsers: run.browsers,
         seconds: secs,
-        note: "An earlier job wrote a test for this flow (written_for) and it passed as it is, in a real browser: no browser run and no new test were needed. If the user's request asks for something written_for does not check, call browser_run again with fresh: true; otherwise say in one or two lines that the existing test passed.",
+        note: asCheck
+          ? "The user's check is answered by this existing test: it does what the check asks and passed just now in a real browser, so no browser run was needed. Report that it passed, naming the test and the command; nothing is written for a check."
+          : `An existing test${known.goal ? " written for written_for" : ""} passed as it is, in a real browser: no browser run and no new test were needed. If the user's request asks for something that test does not do or check, call browser_run again with existing_test set to ${known.test ? "test" : "reused_test"} and existing_mode extend or sibling (the browser runs, and that test is extended, or a test is added beside it, rather than a new one written); otherwise say in one or two lines that the existing test passed.`,
       },
     }
   }
+  if (run.ok && known.derived) {
+    outcome("ran nothing")
+    emit({ type: "info", text: `${known.command} ran no browser test: ForgeQE could not run ${name} on its own, so the browser runs the flow` })
+    return null
+  }
+  outcome(run.ok ? "opened no browser" : "failed")
   const why = run.ok ? "It exits 0 but opened no browser." : `It fails now (${run.exitCode === null ? "timed out" : `exit ${run.exitCode}`}): the application or the page changed since it was written.`
-  emit({ type: "info", text: `${known.test_file} ${run.ok ? "opened no browser" : "fails now"}: ForgeQE runs the flow in the browser, and Scribe updates that test instead of writing a new one` })
+  emit({ type: "info", text: asCheck ? `${name} ${run.ok ? "opened no browser" : "fails now"}: ForgeQE runs the check in the browser` : `${name} ${run.ok ? "opened no browser" : "fails now"}: ForgeQE runs the flow in the browser, and Scribe updates that test instead of writing a new one` })
   return { failed: { testFile: known.test_file, command: known.command, output: run.output, why } }
 }
 
+type ChosenMode = "reuse" | "extend" | "sibling"
+type Chosen = { mode: ChosenMode; file: string; test?: string; runnable?: RunnableTest; repo: string }
+
+/**
+ * The existing test ForgeQE's agent chose: a test id from existing_tests_found (Class.Method) or a file. Reusing it
+ * needs a command: the one an earlier job ran it with, else one built the way the repository runs a single test.
+ */
+async function chosenTest(ref: string, mode: ChosenMode, ctx: ToolContext): Promise<Chosen> {
+  const repo = repoOf(ctx)
+  const graph = await buildGraph(repo).catch(() => null)
+  const tests = graph ? indexTests(graph).map((t) => t.entry) : []
+  const clean = ref.replace(/^\.\//, "")
+  const byId = tests.filter((t) => t.test === clean || t.test.endsWith(`.${clean}`))
+  const file = byId[0]?.file || clean
+  if (!existsSync(path.resolve(repo, file))) throw new Error(`existing_test ${ref} is not a test in ${repo}. Pass a test or test_file from existing_tests_found, or fresh: true.`)
+  const inFile = tests.filter((t) => t.file === file)
+  const test = byId[0]?.test || (inFile.length === 1 ? inFile[0]!.test : undefined)
+  if (mode !== "reuse") return { mode, file, ...(test ? { test } : {}), repo }
+  const known = ctx.config.memory.enabled ? writtenTestFor(ctx.config.memory.dir, repo, file) : null
+  // An earlier job's command runs the test it wrote; for another test in that file, a command is built.
+  const method = test?.split(".").pop() || ""
+  if (known?.command && (!test || inFile.length <= 1 || known.command.includes(method))) return { mode, file, ...(test ? { test } : {}), repo, runnable: { ...known, ...(test ? { test } : {}) } }
+  if (!test && inFile.length > 1) throw new Error(`${file} has ${inFile.length} tests: pass the one to reuse as existing_test (Class.Method, from existing_tests_found).`)
+  const knownCommands = ctx.config.memory.enabled ? writtenTests(ctx.config.memory.dir, repo).map((t) => t.command) : []
+  const command = test ? oneTestCommand(repo, { test, file }, knownCommands, walk(repo)) : null
+  if (!command || !test) throw new Error(`ForgeQE cannot tell how to run ${test || file} on its own: call browser_run with existing_mode extend or sibling to work from it, or write_test with mode reuse after the run.`)
+  return { mode, file, test, repo, runnable: { test_file: file, test, command, derived: true } }
+}
+
+/** Goals the existing-tests check already stopped once in this process: asked again, the browser runs. */
+const gated = new Set<string>()
+/** Existing tests ForgeQE's agent has been shown: fresh: true skips the check only for tests it has seen. */
+const shown = new Set<string>()
+
+/**
+ * Before the browser explores anything: the repository's tests closest to this goal, ranked from the code graph and
+ * page memory without a model (shortlistTests), with the tests earlier jobs wrote for close goals. ForgeQE's agent
+ * compares them with the request and picks: reuse one, extend one, add a test beside one, or run fresh for a new test
+ * that reuses the repository's code. Null when there are none, or this goal was already stopped once.
+ */
+/** A request sent as a task is shown the repository's tests only when they match it this closely. */
+const TASK_FROM = 0.4
+
+async function existingTestsFirst(goal: string, url: string | undefined, fresh: boolean, ctx: ToolContext, asTask = false): Promise<Record<string, unknown> | null> {
+  const cfg = ctx.config
+  if (!cfg.memory.enabled) return null
+  const repo = repoOf(ctx)
+  const key = `${repo}\n${goal.replace(/\s+/g, " ").trim().toLowerCase()}`
+  if (gated.has(key)) {
+    // Shown already: the browser runs, which is the agent's choice, made or not.
+    recordDecision(repo, { goal, stage: "chosen", where: "browser_run", by: "agent", mode: "fresh", why: fresh ? (asTask ? "a task, not a test" : "none of the tests shown is this journey") : "asked again without choosing" })
+    return null
+  }
+  const exists = (f: string) => existsSync(path.resolve(repo, f))
+  // fresh: true asks for a new run of a flow that has a test; for tests only close to it, before the agent has seen
+  // them, it is a guess, not a decision: it sees them first.
+  const written = findRelatedTests(cfg.memory.dir, repo, goal, exists).filter((t) => !fresh || !sameFlow(t.goal, goal))
+  const graph = await buildGraph(repo).catch(() => null)
+  const list = graph ? shortlistTests({ graph, pages: readPages(cfg.memory.dir), request: goal, url }) : null
+  type Shown = { test?: string; test_file: string; line?: number; lines?: number; tests_in_class?: number; tags?: string[]; steps?: string[]; covers?: string[]; lacks?: string[]; why?: string[]; score?: number; written_for?: string; command?: string; written?: string }
+  const out: Shown[] = (list?.candidates || []).filter((c) => !asTask || c.score >= TASK_FROM).map((c) => ({ test: c.test, test_file: c.file, line: c.line, lines: c.lines, tests_in_class: c.siblings + 1, tags: c.tags, steps: c.steps, covers: c.covers, lacks: c.lacks, why: c.why, score: c.score }))
+  // A test an earlier job wrote: its goal and command on the entry for its file, or an entry of its own.
+  for (const w of asTask ? written.filter((t) => t.similarity >= TASK_FROM) : written) {
+    const same = out.find((o) => o.test_file === w.test_file)
+    if (same) Object.assign(same, { written_for: w.goal, command: w.command, written: w.at.slice(0, 10) })
+    else out.push({ test_file: w.test_file, written_for: w.goal, command: w.command, written: w.at.slice(0, 10), score: Number(w.similarity.toFixed(2)) })
+  }
+  const keyOf = (o: Shown) => `${repo}\n${o.test_file}#${o.test || ""}`
+  if (!out.length) return null
+  if (fresh && out.every((o) => shown.has(keyOf(o)))) {
+    recordDecision(repo, { goal, stage: "chosen", where: "browser_run", by: "agent", mode: "fresh", why: asTask ? "a task, not a test" : "none of the tests shown is this journey" })
+    return null
+  }
+  gated.add(key)
+  recordDecision(repo, { goal, stage: "shown", where: "browser_run", ...(asTask ? { why: "sent as a task" } : {}), shown: out.map((o) => ({ ...(o.test ? { test: o.test } : {}), file: o.test_file, ...(o.score !== undefined ? { score: o.score } : {}), ...(o.covers ? { covers: o.covers, lacks: o.lacks } : {}) })) })
+  for (const o of out) shown.add(keyOf(o))
+  const body = out.map((o) => {
+    const what = o.covers?.length || o.lacks?.length ? ` covers ${o.covers!.length} of ${o.covers!.length + o.lacks!.length}${o.lacks!.length ? `; lacks ${o.lacks!.slice(0, 3).join(", ")}${o.lacks!.length > 3 ? ` +${o.lacks!.length - 3}` : ""}` : ""}` : ""
+    return `${o.test || o.test_file}${o.line ? ` (${o.test_file}:${o.line}, ${o.lines} lines)` : ""}${what}${o.written_for ? ` · written for "${o.written_for.replace(/\s+/g, " ").slice(0, 80)}"` : ""}`
+  })
+  ctx.emit?.({
+    type: "card",
+    card: {
+      status: "info",
+      title: `${out.length === 1 ? "An existing test is" : `${out.length} existing tests are`} close to this flow`,
+      stats: `no browser run yet: reuse, extend, or build on them before exploring${list ? ` · ${list.tests} tests searched in ${list.ms}ms` : ""}`,
+      body: [...body, ...(list?.unlocated.length ? [`not in any page object yet: ${list.unlocated.join(", ")}`] : [])],
+    },
+  })
+  return {
+    status: "existing_tests_found",
+    browser: "not started",
+    searched: list ? `${list.tests} tests, ranked from the code graph and page memory` : "the tests earlier jobs wrote",
+    ...(list?.elements.length ? { request_elements: list.elements } : {}),
+    ...(list?.unlocated.length ? { not_in_page_objects: list.unlocated } : {}),
+    existing_tests: out,
+    ...(asTask
+      ? {
+          sent_as: "task",
+          note: "This was sent as a task, but the repository has tests close to it. When one of them does what the request asks, answer the check with it: call browser_run again with the same goal and purpose, existing_test set to that test, and existing_mode reuse. ForgeQE runs it, and the browser runs only when it fails; nothing is written. When the user asked for a test, call browser_run with purpose test and one of the choices in next_step. Only when no test does what it asks, or it needs data a passing test does not give (a value to read or report), call it again with fresh: true.",
+        }
+      : {}),
+    next_step:
+      "Before any browser run, compare each test's steps, covers, lacks, and written_for with the user's request, then call browser_run again with the same goal and one of these: existing_test (its test, or test_file) with existing_mode reuse, when it already does and checks everything the request asks (ForgeQE runs it; no browser run when it passes); existing_mode extend, when it covers the start of the journey and the request adds a few steps or checks to it; existing_mode sibling, when the request is a variant of it (another path, other data, or more than a few added steps, or the test is long already): a new test beside it in its class, reusing its setup and steps; or fresh: true, when none of them is this journey: a new test that still reuses the repository's page objects and helpers.",
+  }
+}
+
 export const TOOLS: McpTool[] = [
   {
     name: "browser_run",
@@ -419,7 +563,17 @@ export const TOOLS: McpTool[] = [
         fresh: {
           type: "boolean",
           description:
-            "true: run in the browser even when an earlier job wrote a test for this goal. Only when the user asks for a new browser run or a new test; by default an existing test is run first and reused when it passes.",
+            "true: run in the browser even when an earlier job wrote a test for this goal or one close to it. Only when the user asks for a new browser run or a new test, or when existing_tests_found listed none that is this journey; by default an existing test is run first and reused when it passes.",
+        },
+        existing_test: {
+          type: "string",
+          description: "A test (Class.Method) or test_file from existing_tests_found, or one the user named, to work from, with existing_mode.",
+        },
+        existing_mode: {
+          type: "string",
+          enum: ["reuse", "extend", "sibling"],
+          description:
+            "With existing_test. reuse: the test already does and checks everything the request asks; ForgeQE runs it, and the browser runs only when it fails. extend: the request adds a few steps or checks to that test's journey; the browser runs the goal and write_test extends that test. sibling: the request is a variant of that test; the browser runs the goal and write_test adds a test beside it in its class, reusing its setup and steps.",
         },
       },
       required: ["goal", "purpose"],
@@ -439,8 +593,30 @@ export const TOOLS: McpTool[] = [
       const emit = ctx.emit || (() => {})
       // The same flow asked again: an earlier job's test for it runs first. Passing in a browser, it answers the goal
       // in seconds, with no browser run and no new test; failing, the run goes ahead and Scribe updates that test.
-      const reuse = ctx.writeTests && args.purpose !== "task" && !args.fresh && !resumeFrom && devices.length <= 1 ? await existingTestFirst(goal, runDir, ctx) : null
+      const mayReuse = ctx.writeTests && args.purpose !== "task" && !resumeFrom && devices.length <= 1
+      // Sent as a task, but close to the repository's tests: the agent may have taken a test of the app for a lookup.
+      // A check of the application, answered by running the existing test that does it: no browser run when it passes.
+      const checkByTest = ctx.writeTests && args.purpose === "task" && !resumeFrom && devices.length <= 1
+      if (checkByTest && !args.existing_test) {
+        const found = await existingTestsFirst(goal, url, Boolean(args.fresh), ctx, true)
+        if (found) return found
+      }
+      const mode: ChosenMode = args.existing_mode === "extend" || args.existing_mode === "sibling" ? args.existing_mode : "reuse"
+      if (checkByTest && args.existing_test && mode !== "reuse") throw new Error(`existing_mode ${mode} writes a test: call browser_run with purpose test for it, or existing_mode reuse to answer the check with that test.`)
+      const chosen = (mayReuse || checkByTest) && args.existing_test ? await chosenTest(String(args.existing_test), mode, ctx) : null
+      let reuse: ExistingFirst | null = null
+      if (chosen) recordDecision(chosen.repo, { goal, stage: "chosen", where: "browser_run", by: "agent", mode: chosen.mode, file: chosen.file, ...(chosen.test ? { test: chosen.test } : {}) })
+      if (chosen?.runnable) reuse = await runKnownTest(chosen.runnable, chosen.repo, runDir, ctx, goal, checkByTest)
+      else if (mayReuse && !chosen) {
+        if (!args.fresh) reuse = await existingTestFirst(goal, runDir, ctx)
+        // Not the same flow, but close to existing tests: decide reuse, extend, or build on one before the browser explores.
+        if (!reuse) {
+          const found = await existingTestsFirst(goal, url, Boolean(args.fresh), ctx)
+          if (found) return found
+        }
+      }
       if (reuse?.passed) return reuse.passed
+      const extend = chosen && chosen.mode !== "reuse" ? chosen : undefined
       const t0 = Date.now()
       emit({ type: "run-start", goal, url })
       try {
@@ -470,10 +646,15 @@ export const TOOLS: McpTool[] = [
         }
         if (ctx.writeTests && result.status === "complete" && result.driver !== "synthetic") {
           if (reuse?.failed) writeFileSync(path.join(runDir, EXISTING_TEST_FILE), `${JSON.stringify(reuse.failed, null, 2)}\n`)
-          return {
-            ...summary,
-            next_step: `This session turns passed runs into tests: call write_test with run_dir ${runDir} now, before you reply.${reuse?.failed ? ` It updates the existing test ${reuse.failed.testFile} instead of writing a new one.` : ""}`,
-          }
+          else if (extend) writeFileSync(path.join(runDir, EXTEND_TEST_FILE), `${JSON.stringify({ testFile: extend.file, ...(extend.test ? { test: extend.test } : {}), mode: extend.mode }, null, 2)}\n`)
+          const how = reuse?.failed
+            ? ` It updates the existing test ${reuse.failed.testFile} instead of writing a new one.`
+            : extend?.mode === "sibling"
+              ? ` It adds a test beside ${extend.test || "the existing test"} in ${extend.file}, reusing its setup and steps, instead of writing a new file.`
+              : extend
+                ? ` It extends the existing test ${extend.file} instead of writing a new one.`
+                : ""
+          return { ...summary, next_step: `This session turns passed runs into tests: call write_test with run_dir ${runDir} now, before you reply.${how}` }
         }
         return summary
       } catch (err) {
@@ -507,7 +688,7 @@ export const TOOLS: McpTool[] = [
   {
     name: "save_test_cases",
     description:
-      "Save test cases you wrote from a story into Azure DevOps (Test Case work items with steps and expected results, linked to the story as Tests / Tested By, in the story's area and iteration) or Jira (issues of type Test by default, steps in the description, linked to the story). A case whose title matches one already linked to the story is reused, not duplicated. Returns each case's id and link, and shows them as a card.",
+      "Save test cases you wrote from a story into Azure DevOps (Test Case work items with steps and expected results, linked to the story as Tests / Tested By, in the story's area and iteration) or Jira (issues of type Test by default, steps in the description, linked to the story). Never duplicates: each case is compared with the cases already linked to the story. Same steps (under any title): unchanged, nothing written. Same title, other steps: differs, nothing written; propose the new steps with update_test_case. A close title or mostly the same steps: similar, nothing written; update that case, or save again with the title in force_new when it is really a different case. Returns each case's status, id, and link, and shows them as a card.",
     inputSchema: {
       type: "object",
       properties: {
@@ -531,6 +712,7 @@ export const TOOLS: McpTool[] = [
         },
         issue_type: { type: "string", description: "Jira only: issue type for the cases (default Test)" },
         link_type: { type: "string", description: "Jira only: link type to the story (default Relates)" },
+        force_new: { type: "array", items: { type: "string" }, description: "Titles to create although a similar case is linked, only after the user said they are different cases" },
       },
       required: ["system", "story", "cases"],
     },
@@ -539,29 +721,55 @@ export const TOOLS: McpTool[] = [
       if (!cases.length) throw new Error("cases is empty.")
       const story = String(args.story || "").trim()
       if (!story) throw new Error("story is required.")
+      const forceNew = Array.isArray(args.force_new) ? (args.force_new as unknown[]).map(String) : undefined
       const saved =
         args.system === "jira"
-          ? await saveJiraCases(ctx.config.sources, story, cases, { issueType: args.issue_type ? String(args.issue_type) : undefined, linkType: args.link_type ? String(args.link_type) : undefined })
-          : await saveAdoCases(ctx.config.sources, Number(story.replace(/^#/, "")), cases)
-      const made = saved.cases.filter((c) => c.created).length
-      const failed = saved.cases.filter((c) => !c.id).length
+          ? await saveJiraCases(ctx.config.sources, story, cases, { issueType: args.issue_type ? String(args.issue_type) : undefined, linkType: args.link_type ? String(args.link_type) : undefined, forceNew })
+          : await saveAdoCases(ctx.config.sources, Number(story.replace(/^#/, "")), cases, { forceNew })
+      const count = (st: SaveStatus) => saved.cases.filter((c) => c.status === st).length
+      const MARKS: Record<SaveStatus, string> = { created: "+", unchanged: "=", differs: "~", similar: "?", failed: "✗" }
+      const failed = count("failed")
       ctx.emit?.({
         type: "card",
         card: {
-          status: failed ? "fail" : "ok",
+          status: failed ? "fail" : count("differs") || count("similar") ? "info" : "ok",
           title: `Test cases saved for ${saved.story.id}${saved.story.title ? ` ${saved.story.title}` : ""}`,
-          stats: [`${made} created`, saved.cases.length - made - failed ? `${saved.cases.length - made - failed} already linked` : "", failed ? `${failed} failed` : ""].filter(Boolean).join(" · "),
+          stats: [`${count("created")} created`, count("unchanged") ? `${count("unchanged")} already linked` : "", count("differs") ? `${count("differs")} differ from the linked case` : "", count("similar") ? `${count("similar")} like a linked case` : "", failed ? `${failed} failed` : ""].filter(Boolean).join(" · "),
           body: [
             `Story     ${saved.story.url}`,
             "",
-            ...saved.cases.flatMap((c) => (c.id ? [`${c.created ? "+" : "="} ${c.id}  ${c.title}`, `    ${c.url}`, ...(c.error ? [`    ${c.error}`] : [])] : [`✗ ${c.title}: ${c.error}`])),
+            ...saved.cases.flatMap((c) =>
+              c.id
+                ? [
+                    `${MARKS[c.status]} ${c.id}  ${c.title}`,
+                    ...(c.existing && c.existing.title !== c.title ? [`    linked as "${c.existing.title}"`] : []),
+                    `    ${c.url}`,
+                    ...(c.error ? [`    ${c.error}`] : []),
+                  ]
+                : [`✗ ${c.title}: ${c.error}`],
+            ),
           ],
         },
       })
+      const show = (steps: NewCase["steps"]) => steps.map((st, i) => `${i + 1}. ${st.action}${st.expected ? ` → ${st.expected}` : ""}`)
+      const pending = saved.cases.filter((c) => c.status === "differs" || c.status === "similar")
       return {
         story: saved.story,
-        cases: saved.cases.map((c) => ({ title: c.title, id: c.id || undefined, url: c.url || undefined, created: c.created, error: c.error })),
-        ...(saved.system === "azure_devops" && saved.cases.some((c) => c.id) ? { run_with: { source: "azure_devops", ids: saved.cases.filter((c) => c.id).map((c) => c.id) } } : {}),
+        cases: saved.cases.map((c) => ({
+          title: c.title,
+          status: c.status,
+          id: c.id || undefined,
+          url: c.url || undefined,
+          ...(c.existing ? { linked_case: { id: c.existing.id, title: c.existing.title, steps: show(c.existing.steps) } } : {}),
+          error: c.error,
+        })),
+        ...(saved.system === "azure_devops" && saved.cases.some((c) => c.id) ? { run_with: { source: "azure_devops", ids: [...new Set(saved.cases.filter((c) => c.id).map((c) => c.id))] } } : {}),
+        ...(pending.length
+          ? {
+              next_step:
+                "Nothing was written for the cases with status differs or similar. Do not say they were saved or updated. For each one, show the user how it differs from linked_case and offer update_test_case with the steps you wrote (id: linked_case.id). Save again with the title in force_new only when the user says it is a different case.",
+            }
+          : {}),
       }
     },
   },
@@ -918,6 +1126,7 @@ export const TOOLS: McpTool[] = [
   ...COMMAND_TOOLS,
   ...REPO_TEST_TOOLS,
   ...DEFECT_TOOLS,
+  ...PACK_TOOLS,
   ...PR_TOOLS,
   ...CASE_TOOLS,
   ...API_TOOLS,