@capagents/forgeqe 1.2.1 → 1.3.1

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,10 +31,12 @@ 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"
 import { CAPABILITY_TOOLS } from "./captools.ts"
+import type { Router } from "./routing.ts"
 import { NOTIFY_TOOLS } from "./notifytools.ts"
 import { REPORT_TOOLS } from "./reporttools.ts"
 import { DEVICE_TOOLS } from "./devicetools.ts"
@@ -135,6 +141,8 @@ export function queryLine(args: Record<string, any>): string {
 
 export type ToolContext = {
   config: AppConfig
+  /** ForgeQE's agent's session: which tools and playbooks it gets on demand (src/mcp/routing.ts). */
+  router?: Router
   /** The repository or folder the agent works in. */
   cwd: string
   headed?: boolean
@@ -330,21 +338,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 +385,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 +566,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 +596,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 +649,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 +691,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 +715,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 +724,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 +1129,7 @@ export const TOOLS: McpTool[] = [
   ...COMMAND_TOOLS,
   ...REPO_TEST_TOOLS,
   ...DEFECT_TOOLS,
+  ...PACK_TOOLS,
   ...PR_TOOLS,
   ...CASE_TOOLS,
   ...API_TOOLS,