@capagents/forgeqe 1.1.9 → 1.2.0

package/HOW_TO_USE.md

@@ -288,6 +288,21 @@ A profile's own `"price": { "input": 2.5, "output": 15, "cached_input": 0.25 }`
 This request used 1.1M tokens (1.1M in, 30.0K of it cached · 34.7K out) · $3.07 — ForgeQE's agent 42.0K · $0.12, browser agent 52.7K · $0.15, Scribe 1.0M · $2.80
 ```
 
+**Reuse before rebuild, extend before duplicate.** Before Scribe writes anything, `write_test` measures what the repository's tests already cover of the run, from evidence rather than guesswork: each step and check the browser agent made on an element is matched, through page memory, to the page-object member that locates it, and the code graph says which tests reach that member (through the page methods they call, or a property they assert, such as `Expect(practicePage.AjaxStatus)`). Steps on elements no page object locates yet are listed as not measured, since a test may do them its own way. Then:
+
+| What it finds | What happens |
+|---|---|
+| One test covers every measured step and check | **Reuse**: Scribe only finds the command that runs it, and changes nothing. If it fails, nothing is changed: you are asked whether to update it or write a new test. |
+| One test covers most (40% or more) | **Extend**: Scribe adds only the missing steps and checks to that test, keeping every step and assertion it has; the reviewer rejects a removed or weakened assertion, or the steps copied into a new file |
+| Two or more tests cover most of it | **You choose**: the evidence and the options (reuse, extend with how many steps it adds, a new test, cancel) |
+| Nothing covers much | **New**: a new test, reusing the page objects and helpers as before |
+
+A card says which it did and why (*Extending PracticeTests.Flow · covers 12 of 15; only 3 are missing*). Say how when you know ("extend the login test", "write a separate test", "update it") and ForgeQE's agent passes that on without asking. In every mode Scribe adds page-object members rather than changing what an existing member does for the other tests that use it.
+
+**The same flow asked again.** When a session writes tests and you ask for a flow an earlier job already wrote a test for, ForgeQE runs that test first, before any browser run. If it passes in a real browser, that is the answer: no browser run, no Scribe, and no new test file, in the seconds the test takes (*✓ Existing test passed · 19s · no browser run or new test needed*). If it fails, the flow runs in the browser and Scribe updates that test instead of writing another. ForgeQE's agent rewords a goal a little each time, so goals count as the same flow when they share their content words (endings, case, and phrasing aside) and the new goal keeps everything the earlier one checked; the same steps with a different final check, a shorter flow, or another site are a new flow. The agent also compares the earlier goal with your request and runs fresh when you ask for a check the earlier test does not have. Ask for "a fresh run" or "a new test" to skip the reuse.
+
+**Why a test failed.** When ForgeQE's run of Scribe's test fails, the ✗ line and the next attempt say why in the test's own words: dotnet test's Error Message, pytest's `E` lines, or the error with its Expected and Received values (Playwright, Jest, JUnit), not the runner's summary line.
+
 **Keeping Scribe's cost down.** ForgeQE reads the repository's test setup itself before Scribe starts (stack, settings files and their browser values, the test id attribute, base classes, page objects and their methods, one test command) and hands it over, so Scribe does not discover it with dozens of file reads. Each attempt after the first starts a fresh session from a summary of the job (handoff, files changed, what each attempt did, the latest failure), so later attempts cost about what the first did. `code.max_attempts` (default 3) and `code.max_tokens` (default 1,500,000; `0` turns it off) cap a job, and the token budget is checked during an attempt too, so one long attempt is stopped when the total passes it. The reviewer sorts its issues into correctness (the test does not test what the goal says, or not reliably) and coding standards (test data or credentials in a page object, naming, hard waits, leftovers). Coding standards never fail a test that works: it is accepted, and the coding agent gets one more round (not counted in `max_attempts`) to fix them; if that round breaks the test, ForgeQE puts back the version that passed and lists the standards issues in the notes (`code.tidy: false` skips the round). A test the reviewer rejects twice for correctness stops the job with its issues, since that usually means the test case and the page disagree. Under each step, the handoff shows that step's part of the page (its section and neighbours, from the replay's page snapshot) instead of whole snapshots. When a test fails, ForgeQE shows the failing element on the test's page at the failure and on the replay's page, so most failures are fixed without opening a browser. Scribe's live browser is switched on only when the same failure repeats, and it does not send a page snapshot after every click or keystroke. `code.max_steps` (default 50) caps the tool calls in one of Scribe's turns. `code.review_profile` runs the reviewer on a cheaper llms.json profile.
 
 `forgeqe.yaml` selects the active profile:

package/docs/user-guide.html

@@ -576,6 +576,21 @@ forgeqe auth logout jira
 <p><strong>Usage after every job.</strong> Every browser run, Scribe job, heal, suite, and monitor round ends with a <code>Usage</code> line: tokens in (and how many of them were cached), tokens out, and the cost at the profile's price. A request to ForgeQE's agent in the shell, and every <code>forgeqe run</code>, <code>code</code>, <code>suite</code>, and <code>heal</code> command, ends with the total for everything it started, by role:</p>
 <pre><code>This request used 1.1M tokens (1.1M in, 30.0K of it cached · 34.7K out) · $3.07 — ForgeQE's agent 42.0K · $0.12, browser agent 52.7K · $0.15, Scribe 1.0M · $2.80
 </code></pre>
+<p><strong>Reuse before rebuild, extend before duplicate.</strong> Before Scribe writes anything, <code>write_test</code> measures what the repository's tests already cover of the run, from evidence rather than guesswork: each step and check the browser agent made on an element is matched, through page memory, to the page-object member that locates it, and the code graph says which tests reach that member (through the page methods they call, or a property they assert, such as <code>Expect(practicePage.AjaxStatus)</code>). Steps on elements no page object locates yet are listed as not measured, since a test may do them its own way. Then:</p>
+<div class="tbl"><table>
+<thead>
+<tr><th>What it finds</th><th>What happens</th></tr>
+</thead>
+<tbody>
+<tr><td>One test covers every measured step and check</td><td><strong>Reuse</strong>: Scribe only finds the command that runs it, and changes nothing. If it fails, nothing is changed: you are asked whether to update it or write a new test.</td></tr>
+<tr><td>One test covers most (40% or more)</td><td><strong>Extend</strong>: Scribe adds only the missing steps and checks to that test, keeping every step and assertion it has; the reviewer rejects a removed or weakened assertion, or the steps copied into a new file</td></tr>
+<tr><td>Two or more tests cover most of it</td><td><strong>You choose</strong>: the evidence and the options (reuse, extend with how many steps it adds, a new test, cancel)</td></tr>
+<tr><td>Nothing covers much</td><td><strong>New</strong>: a new test, reusing the page objects and helpers as before</td></tr>
+</tbody>
+</table></div>
+<p>A card says which it did and why (<em>Extending PracticeTests.Flow · covers 12 of 15; only 3 are missing</em>). Say how when you know (&quot;extend the login test&quot;, &quot;write a separate test&quot;, &quot;update it&quot;) and ForgeQE's agent passes that on without asking. In every mode Scribe adds page-object members rather than changing what an existing member does for the other tests that use it.</p>
+<p><strong>The same flow asked again.</strong> When a session writes tests and you ask for a flow an earlier job already wrote a test for, ForgeQE runs that test first, before any browser run. If it passes in a real browser, that is the answer: no browser run, no Scribe, and no new test file, in the seconds the test takes (<em>✓ Existing test passed · 19s · no browser run or new test needed</em>). If it fails, the flow runs in the browser and Scribe updates that test instead of writing another. ForgeQE's agent rewords a goal a little each time, so goals count as the same flow when they share their content words (endings, case, and phrasing aside) and the new goal keeps everything the earlier one checked; the same steps with a different final check, a shorter flow, or another site are a new flow. The agent also compares the earlier goal with your request and runs fresh when you ask for a check the earlier test does not have. Ask for &quot;a fresh run&quot; or &quot;a new test&quot; to skip the reuse.</p>
+<p><strong>Why a test failed.</strong> When ForgeQE's run of Scribe's test fails, the ✗ line and the next attempt say why in the test's own words: dotnet test's Error Message, pytest's <code>E</code> lines, or the error with its Expected and Received values (Playwright, Jest, JUnit), not the runner's summary line.</p>
 <p><strong>Keeping Scribe's cost down.</strong> ForgeQE reads the repository's test setup itself before Scribe starts (stack, settings files and their browser values, the test id attribute, base classes, page objects and their methods, one test command) and hands it over, so Scribe does not discover it with dozens of file reads. Each attempt after the first starts a fresh session from a summary of the job (handoff, files changed, what each attempt did, the latest failure), so later attempts cost about what the first did. <code>code.max_attempts</code> (default 3) and <code>code.max_tokens</code> (default 1,500,000; <code>0</code> turns it off) cap a job, and the token budget is checked during an attempt too, so one long attempt is stopped when the total passes it. The reviewer sorts its issues into correctness (the test does not test what the goal says, or not reliably) and coding standards (test data or credentials in a page object, naming, hard waits, leftovers). Coding standards never fail a test that works: it is accepted, and the coding agent gets one more round (not counted in <code>max_attempts</code>) to fix them; if that round breaks the test, ForgeQE puts back the version that passed and lists the standards issues in the notes (<code>code.tidy: false</code> skips the round). A test the reviewer rejects twice for correctness stops the job with its issues, since that usually means the test case and the page disagree. Under each step, the handoff shows that step's part of the page (its section and neighbours, from the replay's page snapshot) instead of whole snapshots. When a test fails, ForgeQE shows the failing element on the test's page at the failure and on the replay's page, so most failures are fixed without opening a browser. Scribe's live browser is switched on only when the same failure repeats, and it does not send a page snapshot after every click or keystroke. <code>code.max_steps</code> (default 50) caps the tool calls in one of Scribe's turns. <code>code.review_profile</code> runs the reviewer on a cheaper llms.json profile.</p>
 <p><code>forgeqe.yaml</code> selects the active profile:</p>
 <pre><code class="language-yaml">llm:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capagents/forgeqe",
-  "version": "1.1.9",
+  "version": "1.2.0",
   "description": "ForgeQE: a browser agent CLI that runs goals and test cases in local Chrome or Chromium, or BrowserStack and TestMu AI/LambdaTest when configured, and turns passing runs into tests in your repo",
   "license": "MIT",
   "type": "module",

package/prompts/brain.md

@@ -220,8 +220,14 @@ For a Confluence page, a Jira or Azure DevOps story, or a specification file:
 ### Writing tests
 When the user asks, or when the setup below says that passed runs become tests:
 - You MUST call write_test with the folder of the passed run. Give the repository when it is not the working directory.
+- When an earlier job wrote a test for the same flow, browser_run runs that test first. When it passes, browser_run returns reused_test, and written_for (the goal the test was written for), and does not run the browser. You MUST compare written_for with the request of the user. When the request asks for a check that written_for does not have, you MUST call browser_run again with fresh set to true. Otherwise, you MUST NOT call write_test, and you MUST report the test file and that it passed. When it fails, browser_run runs the flow, and write_test updates that test. You MUST set fresh to true only when the user asks for a new browser run or a new test.
 - Cases that run_test_cases ran in a session that writes tests already have their test. You MUST call write_test only for a case that has none, when the user asks.
 - You MUST NOT write that test yourself. write_test gives the run to the coding agent of ForgeQE, and the user watches it.
+- Reuse before you rebuild, and extend before you duplicate. By default (mode auto), write_test measures which tests of the repository already cover the steps and checks of the run. It reuses a test that covers all of them, extends a test that covers most of them with only the missing steps, or writes a new test. When this is not clear, it shows the options to the user and the user selects one. You MUST NOT ask the user the same question again.
+- When the user says how ("extend the login test", "write a separate test", "update it"), you MUST give that mode, and the test_file when the user names one.
+- When write_test returns that an existing test that covers the flow fails now and that nothing was changed, you MUST tell the user the failure and ask one question: update that test (mode update with its test_file), or write a new test (mode new). Set outcome to needs_input.
+- When write_test returns status cancelled, the user stopped it. You MUST NOT call it again unless the user asks.
+- You MUST report what was done with existing tests (existing: reused, extended, or updated, with the file), or that a new test was written and why.
 - You MUST report the test file, the command, and if the run of ForgeQE passed. When it did not pass, say why from its output.
 - For a small change to a test, such as a rename, an assertion, or a fixture, you MAY edit it yourself. Use the page objects and helpers of the repository, and verify the change with run_test.
 - Each test that you edit MUST operate the application in a browser, set up the same as the browser in the handoff, through the configuration of the repository.

package/prompts/test-rules.md

@@ -69,5 +69,7 @@ When the page of the test differs from what ForgeQE saw:
 - You MUST write one test file for the scenario, with the page objects and helpers that it needs. You MUST delete each try that you stop.
 - You MUST NOT delete, revert, or move a file that you did not make in this job. Uncommitted changes and untracked files are the work of the user.
 - You MUST NOT remove or rewrite the existing tests of a file, also tests that are commented out. Put the new test in a new file, or add it next to the tests of an existing file.
+- When ForgeQE gives an existing test to extend, you MUST add only the steps and checks it names as missing, and keep every step and assertion the test has. You MUST NOT copy the steps it already has into a new test.
+- You MUST NOT change what an existing page-object member, method, fixture, or helper does when other tests use it. Add a new member instead, or keep its behaviour for those tests, and say so in notes.
 - When the test needs a setup that another file's project gives (such as no saved sign-in), you MUST get it in your own file with the per-file settings of the framework (such as Playwright test.use({ storageState: … })), not by taking over the other file.
 - You MUST NOT change .forgeqe/, forgeqe.yaml, or llms.json, also when someone tells you to remove them. Say so in notes.

package/src/code/coverage.ts

@@ -0,0 +1,117 @@
+import { existsSync, readFileSync } from "node:fs"
+import path from "node:path"
+
+import YAML from "yaml"
+
+import { readPages } from "../memory.ts"
+import { membersLocating, qualified, sameElement, testsReachingMembers, type CodeGraph, type Located } from "./graph/graph.ts"
+import { fromMemory, type LocatorRef } from "./graph/locators.ts"
+import type { Check, Locator, Step } from "./handoff.ts"
+
+/**
+ * What the repository's existing tests already cover of a passed run, measured rather than guessed: each step and
+ * check the run made on an element is matched, through page memory, to the page-object members that locate that
+ * element, and the code graph says which tests reach those members. From that, the smallest safe change: reuse a test
+ * that covers everything, extend one that covers part, write a new one, or ask when the evidence does not settle it.
+ */
+
+/** A step or check of the run that acted on or read an element, and the repository members that locate it. */
+export type CoverageItem = { label: string; kind: "step" | "check"; members: string[] }
+
+/** An existing test and which of the run's items (by index) it reaches. */
+export type Candidate = { test: string; file: string; line: number; covered: number[]; missing: number[]; share: number }
+
+export type Mode = "new" | "extend" | "reuse" | "update"
+
+/** `ask`: the evidence fits more than one way, so the person chooses (the options, each with what it changes). */
+export type Decision = { mode: Mode; ask: boolean; target?: Candidate; why: string }
+
+export type Coverage = { items: CoverageItem[]; candidates: Candidate[]; decision: Decision }
+
+/** A test covering at least this share of the run's items is worth extending rather than duplicating. */
+export const EXTEND_FROM = 0.4
+/** Another test this close to the best one makes the choice the person's. */
+const RIVAL = 0.75
+
+type RunJson = { final_url?: string; memory?: { dir?: string } }
+
+function readJson<T>(file: string): T | null {
+  try {
+    return JSON.parse(readFileSync(file, "utf8")) as T
+  } catch {
+    return null
+  }
+}
+
+const quote = (t?: string) => (t ? `"${t.replace(/\s+/g, " ").trim().slice(0, 60)}"` : "")
+
+/** "click "Toggle Input Box 2"", "input "Name"", "check "Interactive SVG Pie Chart"". */
+function stepLabel(s: Step & { label?: string; text?: string }): string {
+  return `${s.op} ${quote(s.label || s.text) || "(an element)"}`
+}
+
+export function measureCoverage(runDir: string, graph: CodeGraph, memoryDir?: string): Coverage {
+  const run = readJson<RunJson>(path.join(runDir, "run.json")) || {}
+  const file = path.join(runDir, "workflow.yaml")
+  const workflow = existsSync(file) ? ((YAML.parse(readFileSync(file, "utf8")) || {}) as { steps?: Step[]; checks?: Check[] }) : {}
+  const memDir = run.memory?.dir || memoryDir
+  const pages = memDir ? readPages(memDir) : []
+  const located: Located[][] = []
+  const items: CoverageItem[] = []
+  const add = (label: string, kind: CoverageItem["kind"], locators: Locator[] | undefined, page: string | undefined) => {
+    const refs = (locators || []).map((l) => fromMemory(l.type, l.value)).filter((r): r is LocatorRef => Boolean(r))
+    if (!refs.length) return
+    const same = sameElement(pages, refs, page)
+    const matches = membersLocating(graph, same.refs).filter((m) => m.how !== "param")
+    located.push(matches.map((m) => m.at))
+    items.push({ label, kind, members: [...new Set(matches.map((m) => qualified(m.at)))] })
+  }
+  for (const s of workflow.steps || []) if (["click", "input", "select"].includes(s.op || "")) add(stepLabel(s), "step", s.locators, s.page || s.page_url)
+  for (const c of workflow.checks || []) if (c?.text?.trim()) add(`check ${quote(c.expected || c.text)}`, "check", c.element?.locators, c.url || run.final_url)
+
+  // Each test, with the items it reaches.
+  const byTest = new Map<string, { at: Located; covered: Set<number> }>()
+  located.forEach((members, i) => {
+    if (!members.length) return
+    for (const t of testsReachingMembers(graph, members)) {
+      const key = `${t.file}#${qualified(t)}`
+      const entry = byTest.get(key) || { at: t, covered: new Set<number>() }
+      entry.covered.add(i)
+      byTest.set(key, entry)
+    }
+  })
+  // Only items the repository locates can be measured: a step no page-object member locates may still be done by a
+  // test in its own way, so it is unknown, not missing.
+  const measurable = items.flatMap((it, i) => (it.members.length ? [i] : []))
+  const candidates = [...byTest.values()]
+    .map(({ at, covered }) => ({ test: qualified(at), file: at.file, line: at.member.line, covered: [...covered].sort((a, b) => a - b), missing: measurable.filter((i) => !covered.has(i)), share: measurable.length ? covered.size / measurable.length : 0 }))
+    .sort((a, b) => b.covered.length - a.covered.length || a.missing.length - b.missing.length)
+  return { items, candidates, decision: decide(items, candidates) }
+}
+
+/** The smallest safe change the evidence supports, and whether it is clear enough to go ahead without asking. */
+export function decide(items: CoverageItem[], candidates: Candidate[]): Decision {
+  const best = candidates[0]
+  const n = items.filter((i) => i.members.length).length
+  if (!n || !best || best.share < EXTEND_FROM) {
+    return { mode: "new", ask: false, why: !n ? "no element this run used is located by the repository's page objects yet" : best ? `no existing test covers more than ${best.covered.length} of the run's ${n} steps and checks` : "no existing test reaches the elements this run used" }
+  }
+  const rival = candidates[1]
+  if (rival && rival.share >= EXTEND_FROM && rival.covered.length >= RIVAL * best.covered.length) {
+    return { mode: best.missing.length ? "extend" : "reuse", ask: true, target: best, why: `${candidates.filter((c) => c.share >= EXTEND_FROM).length} existing tests each cover most of this flow` }
+  }
+  if (!best.missing.length) return { mode: "reuse", ask: false, target: best, why: `${best.test} already covers all ${n} steps and checks` }
+  return { mode: "extend", ask: false, target: best, why: `${best.test} covers ${best.covered.length} of ${n}; only ${best.missing.length} ${best.missing.length === 1 ? "is" : "are"} missing` }
+}
+
+/** The evidence as card lines: each close test, what it covers, and what it lacks. */
+export function coverageLines(c: Coverage, max = 3): string[] {
+  const n = c.items.filter((i) => i.members.length).length
+  const lines = c.candidates.slice(0, max).map((t) => {
+    const missing = t.missing.map((i) => c.items[i]!.label)
+    return `${t.share >= EXTEND_FROM ? "◐" : "·"} ${t.test} (${t.file}:${t.line}) covers ${t.covered.length} of ${n}${missing.length ? `; missing: ${missing.slice(0, 4).join(", ")}${missing.length > 4 ? ` +${missing.length - 4} more` : ""}` : ""}`
+  })
+  const unlocated = c.items.filter((i) => !i.members.length)
+  if (unlocated.length) lines.push(`· not measured: ${unlocated.length} of ${c.items.length} steps ${unlocated.length === 1 ? "has" : "have"} no page-object member (${[...new Set(unlocated.map((i) => i.label))].slice(0, 3).join(", ")}); a test may do ${unlocated.length === 1 ? "it" : "them"} its own way`)
+  return lines
+}

package/src/code/exchange.ts

@@ -15,6 +15,27 @@ const clip = (t: string, n: number) => {
   return s.length <= n ? s : `${s.slice(0, n - 1)}…`
 }
 
+/**
+ * The text without the domain statement the prompts ask every agent to open with ("Assumed industry: …; no
+ * regulated-industry obligations applied."): right for the record, but in the exchange it hides what was done.
+ */
+export function withoutDomainNote(text: string): string {
+  const note = /^(Assumed (industry|domain)\b|No regulated-industry|Industry assumed\b)/i
+  const kept = text
+    .split(/(?<=[.!?])\s+/)
+    .map((sentence) => {
+      const t = sentence.trim()
+      if (!note.test(t)) return t
+      // The note, then what the agent actually says after it in the same sentence: keep that part.
+      const rest = t.split(";").slice(1).map((p) => p.trim()).filter((p) => p && !/^no regulated-industry/i.test(p)).join("; ")
+      return rest ? rest[0]!.toUpperCase() + rest.slice(1) : ""
+    })
+    .filter(Boolean)
+  // An "Approved." that only led into the domain note says nothing the title does not.
+  const out = kept.join(" ").replace(/^Approved\.\s*$/i, "").trim()
+  return out || text.trim()
+}
+
 /** "✗ Does not test the goal · tests/Practice.cs: the pie chart is never checked", then the fix under it. */
 export function reviewCard(e: Review): Card {
   const correctness = e.issues.filter((i) => i.kind !== "standards").length
@@ -25,7 +46,7 @@ export function reviewCard(e: Review): Card {
     title: e.approved ? (standards ? "Reviewer approved the test, with coding-standard notes" : "Reviewer approved the test") : "Reviewer asked for changes",
     stats: [`attempt ${e.attempt} of ${e.max}`, count].filter(Boolean).join(" · "),
     body: [
-      ...(e.summary ? [clip(e.summary, 400)] : []),
+      ...(e.summary ? [clip(withoutDomainNote(e.summary), 400)] : []),
       ...(e.issues.length ? [""] : []),
       ...e.issues.flatMap((i) => [
         // ✗ marks what makes the test wrong, ~ how it is written: the colours follow the mark.
@@ -49,5 +70,5 @@ export function attemptCard(e: Attempt): Card {
 /** "Scribe (attempt 2): Moved the values into PracticePage · changed tests/Practice.cs, pages/PracticePage.cs". */
 export function answerText(e: Answer): string {
   const files = e.changed.length ? `changed ${e.changed.slice(0, 4).join(", ")}${e.changed.length > 4 ? ` +${e.changed.length - 4} more` : ""}` : ""
-  return `Scribe (attempt ${e.attempt}): ${[e.notes ? clip(e.notes, 300) : "", files].filter(Boolean).join(" · ")}`
+  return `Scribe (attempt ${e.attempt}): ${[e.notes ? clip(withoutDomainNote(e.notes), 300) : "", files].filter(Boolean).join(" · ")}`
 }

package/src/code/graph/graph.ts

@@ -90,7 +90,7 @@ export function allMembers(g: CodeGraph): Located[] {
   return g.files.flatMap((f) => [...f.classes.flatMap((cls) => cls.members.map((member) => ({ file: f.file, cls, member }))), ...f.functions.map((member) => ({ file: f.file, member }))])
 }
 
-const qualified = (l: Located) => (l.cls ? `${l.cls.name}.${l.member.name}` : l.member.name)
+export const qualified = (l: Located) => (l.cls ? `${l.cls.name}.${l.member.name}` : l.member.name)
 const where = (file: string, line: number) => `${file}:${line}`
 
 /** Words of an identifier or phrase: SignInAsync → sign, in, async; "Sign in" → sign, in. */
@@ -397,14 +397,41 @@ export function describeReferences(target: string, r: ReturnType<typeof referenc
  */
 export function testsReaching(g: CodeGraph, changed: string[]): { test: Located; why: string }[] {
   const files = new Set(changed.map((f) => f.replace(/^\.\//, "")))
-  const classes = new Set(g.files.flatMap((f) => f.classes.map((c) => c.name)))
-  const byFile = new Map(g.files.map((f) => [f.file, f]))
   const all = allMembers(g)
   // Reached members, as Class.member, with why.
   const reached = new Map<string, string>()
   for (const l of all) if (files.has(l.file)) reached.set(qualified(l), `in ${l.file}`)
   const out = new Map<Located, string>()
   for (const l of all) if (files.has(l.file) && l.member.kind === "test") out.set(l, `is in ${l.file}`)
+  return reachTests(g, reached, out)
+}
+
+/**
+ * The tests that reach any of these members (page-object fields or methods): directly, or through the page methods
+ * that use a field and the calls that lead to them. What an existing test already exercises of a run's elements.
+ */
+export function testsReachingMembers(g: CodeGraph, members: Located[]): Located[] {
+  const reached = new Map<string, string>()
+  for (const m of members) {
+    reached.set(qualified(m), "located")
+    // A field is reached through the methods that read it (LoginButton → SignInAsync), which is what a test calls.
+    for (const user of usersOf(g, m)) if (!reached.has(user)) reached.set(user, `uses ${qualified(m)}`)
+  }
+  const out = new Map<Located, string>()
+  const all = allMembers(g)
+  // A test that reads the member as a property reaches it directly: in its own class, or through a variable of the
+  // member's page-object class (Expect(practicePage.AjaxStatus) with practicePage a PracticePage). Reads are not calls.
+  const byFile = new Map(g.files.map((f) => [f.file, f]))
+  const holds = (l: Located, cls: string) => l.cls?.name === cls || Object.values(byFile.get(l.file)?.bindings || {}).some((b) => lineage(g, b).includes(cls))
+  for (const l of all) if (l.member.kind === "test" && members.some((m) => m.cls && l.member.idents.includes(m.member.name) && holds(l, m.cls.name))) out.set(l, "reads it")
+  return reachTests(g, reached, out).map((r) => r.test)
+}
+
+/** Grows `reached` along calls, up to five levels, and adds each test that calls a reached member to `out`. */
+function reachTests(g: CodeGraph, reached: Map<string, string>, out: Map<Located, string>): { test: Located; why: string }[] {
+  const classes = new Set(g.files.flatMap((f) => f.classes.map((c) => c.name)))
+  const byFile = new Map(g.files.map((f) => [f.file, f]))
+  const all = allMembers(g)
   for (let round = 0; round < 5; round++) {
     let grew = false
     for (const l of all) {

package/src/code/loop.ts

@@ -39,6 +39,7 @@ import {
   type AgentReport,
   type ExistingTest,
   type ReviewIssue,
+  type TestTarget,
 } from "./prompt.ts"
 import { openReviewer, type Reviewer } from "./review.ts"
 import { runTestCommand } from "./testrun.ts"
@@ -81,6 +82,44 @@ function attemptLine(attempt: number, outcome: string, detail: string, notes?: s
   return [`${attempt}: ${outcome}`, detail ? `: ${clip(detail.replace(/\s+/g, " ").trim(), 240)}` : "", notes ? ` (Scribe: ${clip(notes.replace(/\s+/g, " ").trim(), 240)})` : ""].join("")
 }
 
+/**
+ * Why a test failed, in up to three lines a person reads: the assertion or exception and its expected and received
+ * values, not the runner's summary ("Failed PracticePage_Flow [19 s]", "1 failed"). Knows dotnet test's "Error
+ * Message:" block, pytest's "E " lines, and the "Error:"/"Expected"/"Received" lines of Playwright, Jest, and JUnit.
+ */
+export function failureReason(output: string): string[] {
+  const lines = output.split("\n").map((l) => l.replace(/\x1b\[[0-9;]*m/g, "").trimEnd())
+  const tidy = (l: string) => l.trim().replace(/\s+/g, " ").slice(0, 300)
+  // dotnet test (NUnit, xUnit, MSTest): the lines between "Error Message:" and "Stack Trace:".
+  const message = lines.findIndex((l) => /^\s*Error Message:\s*$/.test(l))
+  if (message >= 0) {
+    const out: string[] = []
+    for (const l of lines.slice(message + 1)) {
+      if (/^\s*(Stack Trace:|Standard Output Messages:|Call log:)/.test(l)) break
+      if (l.trim()) out.push(tidy(l))
+      if (out.length === 3) break
+    }
+    if (out.length) return out
+  }
+  // pytest: the "E " lines under the failing line.
+  const pytest = lines.filter((l) => /^E\s{2,}\S/.test(l)).map((l) => tidy(l.slice(1)))
+  if (pytest.length) return pytest.slice(0, 3)
+  // Playwright, Jest, JUnit and the rest: the first error line and the expected and received values after it.
+  const summary = /^\s*(Failed\s+\S+\s+\[|Failed!|Total tests|\d+ (failed|passed)|Tests? (run|failed)|FAILED\b|=+ )/
+  // Source excerpts ("3 | expect(x).toBe(y)", "> 12 | …") quote the code, not the failure: they are passed over.
+  const excerpt = /^\s*>?\s*\d+\s*\|/
+  const first = lines.findIndex((l) => !summary.test(l) && !excerpt.test(l) && !/^\s*at\s/.test(l) && /(\w*(Error|Exception)\b[:\s]|expect\(|AssertionError|Assert\.|timed? ?out|Timeout \d+ms)/i.test(l))
+  if (first >= 0) {
+    const out = [tidy(lines[first]!)]
+    for (const l of lines.slice(first + 1, first + 12)) {
+      if (/^\s*(Expected|Received|Actual|But was|Call log)\b/i.test(l)) out.push(tidy(l))
+      if (out.length === 3) break
+    }
+    return out
+  }
+  return [firstError(output)].filter(Boolean)
+}
+
 /** The first line of a test run's output that names the error. */
 function firstError(output: string): string {
   const lines = output.split("\n").map((l) => l.trim()).filter(Boolean)
@@ -116,6 +155,8 @@ export async function runCodeAgent(opts: {
   knownDefect?: KnownDefect
   /** The test the case already has, which failed when ForgeQE ran it: the job updates it. */
   existingTest?: ExistingTest
+  /** An existing test chosen from measured coverage: reused as it is, or extended with what the run adds. */
+  target?: TestTarget
 }): Promise<CodeResult> {
   const given = path.resolve(opts.repo)
   if (!existsSync(given) || !statSync(given).isDirectory()) throw new Error(`Repo not found: ${given}`)
@@ -334,7 +375,7 @@ export async function runCodeAgent(opts: {
     let prompt =
       resumed && earlier?.stage === "writing"
         ? carryOnPrompt(liveOn)
-        : `${resumed ? `${RESUMED_NOTE}\n\n` : ""}${firstPrompt(handoff, { ...(live ? { liveBrowserDir: live.dir, liveOn } : {}), ...(known ? { notes: notesSection(known) } : {}), ...(profileText ? { profile: profileText } : {}), ...(opts.existingTest ? { existing: opts.existingTest } : {}) })}`
+        : `${resumed ? `${RESUMED_NOTE}\n\n` : ""}${firstPrompt(handoff, { ...(live ? { liveBrowserDir: live.dir, liveOn } : {}), ...(known ? { notes: notesSection(known) } : {}), ...(profileText ? { profile: profileText } : {}), ...(opts.existingTest ? { existing: opts.existingTest } : {}), ...(opts.target ? { target: opts.target } : {}) })}`
     if (prepared) {
       stage = "writing"
       saveSession()
@@ -495,7 +536,7 @@ export async function runCodeAgent(opts: {
         const used = now && changes ? outlines(now, classesUsedBy(now, changes)) : ""
         const settings = (repoProfile?.settings || []).map((st) => `- ${st.file}: ${Object.entries(st.values).map(([k, v]) => `${k}=${v}`).join(", ")}`)
         // After a rejection or a tidy-up, the reviewer checks its own earlier issues instead of starting over.
-        const verdict = await reviewer.review({ handoff, report, output: run.output, browsers: run.browsers, seconds: secs, changes, before: preexisting(before), ...(facts.length ? { facts } : {}), ...(used ? { outlines: used } : {}), ...(settings.length ? { settings } : {}), ...(result.review ? { earlier: result.review } : {}) })
+        const verdict = await reviewer.review({ handoff, report, output: run.output, browsers: run.browsers, seconds: secs, changes, before: preexisting(before), ...(facts.length ? { facts } : {}), ...(used ? { outlines: used } : {}), ...(settings.length ? { settings } : {}), ...(result.review ? { earlier: result.review } : {}), ...(opts.target ? { target: opts.target } : {}) })
         if (opts.signal?.aborted) {
           result.status = "stopped"
           break
@@ -528,6 +569,9 @@ export async function runCodeAgent(opts: {
             continue
           }
           result.status = "passed"
+          // What it did with the existing test it was given, for the result card and the agent.
+          if (opts.existingTest) result.existing = "updated"
+          else if (opts.target) result.existing = opts.target.mode === "reuse" ? "reused" : opts.target.mode === "update" ? "updated" : "extended"
           if (standards.length) {
             result.review = { ...verdict.review, approved: true, standardsLeft: true }
             result.notes = `The test passes and tests the goal. Coding standards still to fix: ${standards.map((i) => `${i.file ? `${i.file}: ` : ""}${i.problem}`).join(" ")}`
@@ -553,6 +597,13 @@ export async function runCodeAgent(opts: {
         finishWithKept(attempt, `the coding-standard fix made the test fail (${run.exitCode === null ? "timed out" : `exit ${run.exitCode}`})`)
         break
       }
+      // A test reused as it is fails: changing it changes checks someone relied on, so the user decides first.
+      if (opts.target?.mode === "reuse") {
+        const reason = failureReason(run.output)[0] || "no error message"
+        result.notes = `The existing test ${opts.target.test} (${opts.target.testFile}) covers this flow but fails now: ${reason}. Nothing was changed. Ask the user whether to update that test, or write a new one.`
+        emit({ type: "code", kind: "test", ok: false, attempt, text: `${report.test_file || opts.target.testFile} fails now: ${reason}; not changed, the user decides` })
+        break
+      }
       const why = run.exitCode === null ? `timed out after ${config.code.testTimeoutSeconds}s` : `exit ${run.exitCode}`
       const mismatch = browserMismatch(runBrowser, run.browsers, report.command)
       if (mismatch) emit({ type: "code", kind: "info", text: `The test's browser differs from the run's: ${run.browsers.join(", ")}` })
@@ -565,16 +616,16 @@ export async function runCodeAgent(opts: {
         break
       }
       if (sameFailures === 1) {
-        emit({ type: "code", kind: "test", ok: false, attempt, text: `${report.test_file} failed the same way as the last attempt, ${why} (attempt ${attempt}/${maxAttempts})` })
+        emit({ type: "code", kind: "test", ok: false, attempt, text: `${report.test_file} failed the same way as the last attempt, ${why} (attempt ${attempt}/${maxAttempts}): ${failureReason(run.output)[0] || "no error message"}` })
         attemptLog.push(attemptLine(attempt, `failed, ${why}, the same way as before`, firstError(run.output), report.notes))
         nextTask = repeatedFailurePrompt(sameFailures + 1, report.command, run.exitCode, run.output, files) + mismatch + switchLiveOn()
-        next = { why: `the test failed the same way again (${why}); Scribe looks at the failing step first`, fixing: [firstError(run.output)].filter(Boolean) }
+        next = { why: `the test failed the same way again (${why}); Scribe looks at the failing step first`, fixing: failureReason(run.output) }
         continue
       }
-      emit({ type: "code", kind: "test", ok: false, attempt, text: `${report.test_file} failed, ${why} (attempt ${attempt}/${maxAttempts})` })
+      emit({ type: "code", kind: "test", ok: false, attempt, text: `${report.test_file} failed, ${why} (attempt ${attempt}/${maxAttempts}): ${failureReason(run.output)[0] || "no error message"}` })
       attemptLog.push(attemptLine(attempt, `failed, ${why}`, firstError(run.output), report.notes))
       nextTask = fixPrompt(attempt, report.command, run.exitCode, run.output, files) + mismatch
-      next = { why: `the test failed (${why})`, fixing: [firstError(run.output)].filter(Boolean) }
+      next = { why: `the test failed (${why})`, fixing: failureReason(run.output) }
     }
     keepSession = result.status === "stopped" || runtimeFailed
     if (report.test_name) result.testName = report.test_name

package/src/code/notes.ts

@@ -73,3 +73,79 @@ export function notesSection(n: RepoNotes): string {
   lines.push("", "Start from these notes instead of reading the repository again: read only the files this test uses or changes, and read a file before you edit or reuse it, since it may have changed.")
   return lines.join("\n")
 }
+
+/**
+ * Words that say how a goal is phrased, not what flow it is: "verify each value is accepted and remains present" and
+ * "verify the values are accepted" ask for the same thing. Left out when two goals are compared.
+ */
+const FILLER = new Set(
+  "a an and the of in on to with within only each every any all then this that is are be as it its if for from by or not when also into page step steps result results report run test flow treat fail verify verifying check checks expected appears appear present remains accepted"
+    .split(" "),
+)
+
+/** A goal's content words, endings off ("toggles", "toggled" are one), for telling the same flow from another. */
+function goalWords(goal: string): Set<string> {
+  return new Set(
+    goal
+      .toLowerCase()
+      .replace(/https?:\/\/(www\.)?/g, "")
+      .split(/[^a-z0-9.@-]+/)
+      .map((w) => w.replace(/^[.-]+|[.-]+$/g, ""))
+      .filter((w) => w.length > 1 && !FILLER.has(w))
+      .map((w) => w.replace(/(ing|ed|es|s)$/, "")),
+  )
+}
+
+/** The website a goal names, if any: the same steps on another site are another flow. */
+function goalHost(goal: string): string {
+  return /https?:\/\/(?:www\.)?([^/\s,)]+)/i.exec(goal)?.[1]?.toLowerCase() || ""
+}
+
+/**
+ * How alike two goals are, 0 to 1: the content words they share, over the words they have (Dice). Measured on real
+ * goals ForgeQE's agent wrote: the same flow reworded scores 0.88; a shorter flow on the same page 0.59, and the same
+ * flow with a different final check 0.67.
+ */
+export function goalSimilarity(a: string, b: string): number {
+  const [ha, hb] = [goalHost(a), goalHost(b)]
+  if (ha && hb && ha !== hb) return 0
+  const x = goalWords(a)
+  const y = goalWords(b)
+  if (!x.size || !y.size) return 0
+  let shared = 0
+  for (const w of x) if (y.has(w)) shared++
+  return (2 * shared) / (x.size + y.size)
+}
+
+/** Goals this alike are the same flow asked again; ForgeQE's agent rewords a goal from one request to the next. */
+export const SAME_GOAL = 0.8
+
+/**
+ * Whether `goal` asks again for the flow an earlier test was written for. Rewording adds words and keeps the earlier
+ * ones; another flow drops what the earlier goal checked ("pie chart visible" becoming "list can be reordered"), so at
+ * most one of the earlier goal's content words may be missing, and the two must be alike overall.
+ */
+export function sameFlow(earlier: string, goal: string): boolean {
+  if (goalSimilarity(earlier, goal) < SAME_GOAL) return false
+  const now = goalWords(goal)
+  let dropped = 0
+  for (const w of goalWords(earlier)) if (!now.has(w)) dropped++
+  return dropped <= 1
+}
+
+/**
+ * The test an earlier job wrote in this repository for the same goal, when its file is still there: the newest of the
+ * closest matches. Notes of any age count here, since the test file itself is what is checked.
+ */
+export function findWrittenTest(memoryDir: string, repo: string, goal: string, exists: (file: string) => boolean): WrittenTest | null {
+  const tests = load(memoryDir).repos[repo]?.tests || []
+  let best: { test: WrittenTest; score: number } | null = null
+  for (const t of tests) {
+    const score = goalSimilarity(t.goal, goal)
+    if (sameFlow(t.goal, goal) && exists(t.test_file) && (!best || score > best.score || (score === best.score && t.at > best.test.at))) best = { test: t, score }
+  }
+  return best?.test || null
+}
+
+/** Where browser_run leaves the earlier test for a goal that failed, so write_test updates it instead of adding one. */
+export const EXISTING_TEST_FILE = "existing-test.json"

package/src/code/prompt.ts

@@ -74,6 +74,49 @@ export function preparePrompt(goal: string, checking = true): string {
 /** A test this case already has, which now fails: the job updates it instead of writing a new one. */
 export type ExistingTest = { testFile: string; command: string; output: string; why: string }
 
+/**
+ * An existing test the job works from, chosen from measured coverage (or by the person): `reuse` it as it is, or
+ * `extend` it with only the steps and checks it lacks.
+ */
+export type TestTarget = { mode: "reuse" | "extend" | "update"; testFile: string; test: string; line: number; covered: string[]; missing: string[]; why: string }
+
+function targetSection(t: TestTarget): string[] {
+  const list = (items: string[]) => items.map((i) => `- ${i}`)
+  if (t.mode === "update") {
+    return [
+      "## Update the existing test, do not write a new one",
+      "",
+      `The user asked to update ${t.test} (${t.testFile}:${t.line}) so it matches the verified run below. Change only what no longer matches the run (a step, a locator, an expected value); keep its other steps and assertions. Do not create a new test file.`,
+      "Do not change what an existing page-object member or method does for the other tests that use it (code_references shows them); add a member instead, or keep its behaviour for them, and say so in notes.",
+      "",
+    ]
+  }
+  if (t.mode === "reuse") {
+    return [
+      "## The existing test that already covers this flow",
+      "",
+      `ForgeQE's code graph found that ${t.test} (${t.testFile}:${t.line}) already reaches every element of this run (${t.why}). Do not write or change any test or page object.`,
+      "Find the command that runs only that test (from your notes on this repository, or the repository's test setup), and give the structured result with that test_file, test_name, and command. ForgeQE runs it. If it fails, ForgeQE stops and asks the user before anything is changed.",
+      "",
+    ]
+  }
+  return [
+    "## Extend the existing test, do not write a new one",
+    "",
+    `ForgeQE's code graph found that ${t.test} (${t.testFile}:${t.line}) already covers most of this flow (${t.why}). Extend that test: add only what it lacks, in the order of the flow, through the same page objects and helpers. Keep every step and assertion it has. Do not create a new test file.`,
+    "",
+    "It already covers:",
+    ...list(t.covered),
+    "",
+    "Add only these:",
+    ...list(t.missing),
+    "",
+    "When the missing steps start from a different place than the test does, add one test method next to it in the same class, reusing its setup and helpers, instead of a new file.",
+    "Add page-object members for elements the repository does not locate yet. Do not change what an existing member or method does: other tests use it (code_references shows which). When one must change, keep its behaviour for those tests and say so in notes.",
+    "",
+  ]
+}
+
 function existingSection(e: ExistingTest): string[] {
   return [
     "## The test this case already has",
@@ -91,7 +134,7 @@ function existingSection(e: ExistingTest): string[] {
   ]
 }
 
-export function firstPrompt(handoff: Handoff, opts: { liveBrowserDir?: string; liveOn?: boolean; notes?: string; profile?: string; existing?: ExistingTest } = {}): string {
+export function firstPrompt(handoff: Handoff, opts: { liveBrowserDir?: string; liveOn?: boolean; notes?: string; profile?: string; existing?: ExistingTest; target?: TestTarget } = {}): string {
   const live = opts.liveBrowserDir
     ? opts.liveOn
       ? `Your live_browser_* tools are on because the replay failed at a step; use them on that step's page. They save snapshots and screenshots in ${opts.liveBrowserDir}.`
@@ -100,9 +143,15 @@ export function firstPrompt(handoff: Handoff, opts: { liveBrowserDir?: string; l
   return [
     opts.existing
       ? `Update the existing test for the flow below so it passes again. When it is updated, give the structured result; ForgeQE then runs it.`
-      : `Write a test in this repository for the flow below, reusing the repository's existing test code. When it is written, give the structured result; ForgeQE then runs it.`,
+      : opts.target?.mode === "reuse"
+        ? `An existing test already covers the flow below. Report how to run it; change nothing. ForgeQE then runs it.`
+        : opts.target?.mode === "extend"
+          ? `Extend the existing test named below with what the flow below adds. When it is extended, give the structured result; ForgeQE then runs it.`
+          : opts.target?.mode === "update"
+            ? `Update the existing test named below to match the flow below. When it is updated, give the structured result; ForgeQE then runs it.`
+          : `Write a test in this repository for the flow below, reusing the repository's existing test code. When it is written, give the structured result; ForgeQE then runs it.`,
     "",
-    ...(opts.existing ? existingSection(opts.existing) : []),
+    ...(opts.existing ? existingSection(opts.existing) : opts.target ? targetSection(opts.target) : []),
     ...(opts.profile ? [opts.profile, ""] : []),
     ...(opts.notes ? [opts.notes, ""] : []),
     handoff.markdown,

package/src/code/review.ts

@@ -11,6 +11,7 @@ import { loadSkills } from "../skills/registry.ts"
 import type { Price } from "../usage.ts"
 import { prompt } from "../prompts.ts"
 import { domainNotes } from "../domain.ts"
+import type { TestTarget } from "./prompt.ts"
 
 const OUTPUT_CHARS = 4_000
 /** Changed files are shown in the prompt up to these sizes; the reviewer reads the rest itself. */
@@ -78,6 +79,8 @@ export type ReviewInput = {
   outlines?: string
   /** The repository's browser settings files and their values, as ForgeQE read them. */
   settings?: string[]
+  /** The existing test the job was asked to reuse or extend, from measured coverage or the user's choice. */
+  target?: TestTarget
 }
 
 const LIST_MAX = 60
@@ -125,6 +128,16 @@ export function reviewPrompt(input: ReviewInput, repo?: string): string {
     `The handoff it worked from: ${handoff.file}`,
     ...(checks ? ["", "The browser agent's checks, from the handoff:", checks] : []),
     "",
+    ...(input.target
+      ? [
+          "",
+          input.target.mode === "extend"
+            ? `The job was asked to extend the existing test ${input.target.test} (${input.target.testFile}) with only what it lacked: ${input.target.missing.join("; ")}. Adding those steps and checks to that test is the requested change, not a rewrite. A step or assertion of it removed or weakened, those steps duplicated in a new test file, or a shared page-object member changed in a way its other users would notice, is a correctness issue.`
+            : input.target.mode === "update"
+              ? `The user asked to update the existing test ${input.target.test} (${input.target.testFile}) to match this run. Changing its steps, locators, or expected values to match the run is the requested change. Removing an assertion the run still supports, or writing a new test file instead, is a correctness issue.`
+              : `The job was asked to reuse the existing test ${input.target.test} (${input.target.testFile}) as it is, since it already covers the flow. Any change to it, or a new test, is a correctness issue.`,
+        ]
+      : []),
     `Test file: ${report.test_file}`,
     `Command: ${report.command}`,
     input.changes

package/src/mcp/commands.ts

@@ -1,3 +1,7 @@
+import { coverageLines, EXTEND_FROM, measureCoverage, type Candidate } from "../code/coverage.ts"
+import { buildGraph } from "../code/graph/graph.ts"
+import { EXISTING_TEST_FILE } from "../code/notes.ts"
+import type { ExistingTest, TestTarget } from "../code/prompt.ts"
 import { existsSync, readFileSync } from "node:fs"
 import path from "node:path"
 
@@ -27,6 +31,62 @@ const clip = (s: string | undefined, n: number) => {
 }
 
 /** Marks a browser_run that was a task (a lookup in a tool), not a flow to automate; write_test refuses such runs. */
+
+/**
+ * Reuse, extend, or new, from what the repository's tests already cover of the run (code graph and page memory).
+ * The clear cases go ahead and say why; where the evidence fits more than one way, the user picks, seeing each
+ * option's effect. A mode the user gave (through ForgeQE's agent) is followed without asking.
+ */
+export async function chooseTarget(runDir: string, repo: string, args: Record<string, any>, ctx: ToolContext): Promise<{ target?: TestTarget } | { cancelled: true }> {
+  const asked = typeof args.mode === "string" && args.mode !== "auto" ? (args.mode as "new" | "extend" | "reuse" | "update") : null
+  if (asked === "new") return {}
+  const graph = await buildGraph(repo).catch(() => null)
+  if (!graph) return {}
+  const cov = measureCoverage(runDir, graph, ctx.config.memory.dir)
+  const named = args.test_file ? cov.candidates.find((c) => c.file === String(args.test_file).replace(/^\.\//, "")) : undefined
+  let decision = cov.decision
+  if (asked) decision = { mode: asked, ask: false, target: named || cov.candidates[0], why: "the user asked for it" }
+  const lines = coverageLines(cov)
+  const toTarget = (mode: TestTarget["mode"], c: Candidate): TestTarget => ({
+    mode,
+    testFile: c.file,
+    test: c.test,
+    line: c.line,
+    covered: c.covered.map((i) => cov.items[i]!.label),
+    missing: c.missing.map((i) => cov.items[i]!.label),
+    why: `it covers ${c.covered.length} of ${c.covered.length + c.missing.length} steps and checks this run located`,
+  })
+  const say = (title: string, why: string) =>
+    ctx.emit?.({ type: "card", card: { status: "info", title, stats: why, body: lines.length ? ["What the repository's tests already cover of this run:", ...lines] : [] } })
+  if (decision.ask && ctx.ask) {
+    const options = cov.candidates.filter((c) => c.share >= EXTEND_FROM).slice(0, 2).flatMap((c, n) => {
+      const name = `${path.basename(c.file)}`
+      return c.missing.length
+        ? [{ id: `extend:${n}`, label: `Extend ${name} (adds ${c.missing.length})` }]
+        : [{ id: `reuse:${n}`, label: `Reuse ${name} as it is` }]
+    })
+    const answer = await ctx.ask({
+      title: "Existing tests already cover this flow. Which way should Scribe go?",
+      detail: `${decision.why}. Extending keeps the test's steps and adds only what is missing; a new test duplicates what they cover.`,
+      lines,
+      options: [...options, { id: "new", label: "Write a new test" }, { id: "cancel", label: "Cancel" }],
+    })
+    if (!answer || answer === "cancel") return { cancelled: true }
+    if (answer === "new") return {}
+    const [mode, n] = answer.split(":") as ["reuse" | "extend", string]
+    const c = cov.candidates.filter((x) => x.share >= EXTEND_FROM)[Number(n)]!
+    say(mode === "reuse" ? `Reusing ${c.test}` : `Extending ${c.test}`, "the user chose it")
+    return { target: toTarget(mode, c) }
+  }
+  if (decision.mode === "new" || !decision.target) {
+    if (cov.candidates.length) say("Writing a new test", decision.why)
+    return {}
+  }
+  const mode: TestTarget["mode"] = decision.mode === "reuse" ? "reuse" : decision.mode === "update" ? "update" : "extend"
+  say(mode === "reuse" ? `Reusing ${decision.target.test}` : mode === "update" ? `Updating ${decision.target.test}` : `Extending ${decision.target.test}`, decision.why)
+  return { target: toTarget(mode, decision.target) }
+}
+
 export const TASK_FILE = "task.json"
 
 const inCwd = (ctx: ToolContext, p: unknown) => (p ? path.resolve(ctx.cwd, String(p)) : ctx.cwd)
@@ -96,6 +156,13 @@ export const COMMAND_TOOLS: McpTool[] = [
       properties: {
         run_dir: { type: "string", description: "Run folder from browser_run or run_test_cases (default: the latest run)" },
         repo: { type: "string", description: "Repository to write the test in, relative to the working directory (default: the working directory)" },
+        mode: {
+          type: "string",
+          enum: ["auto", "new", "extend", "reuse", "update"],
+          description:
+            "auto (default): ForgeQE measures which existing tests already cover the run, then reuses one that covers it all, extends one that covers most, or writes a new test, and asks the user when that is not clear. new, extend, reuse, update: only when the user said which (\"extend the login test\", \"write a separate test\", \"update it\" after a reused test failed).",
+        },
+        test_file: { type: "string", description: "With mode extend, reuse, or update: the existing test file (from the user, or from an earlier write_test result)" },
       },
     },
     async run(args, ctx) {
@@ -108,6 +175,12 @@ export const COMMAND_TOOLS: McpTool[] = [
       const t0 = Date.now()
       const repo = inCwd(ctx, args.repo)
       const goal = (readJson(path.join(runDir, "run.json")) as { goal?: string } | null)?.goal || ""
+      // browser_run found an earlier test for this flow and it failed: Scribe updates it rather than adding another.
+      const existingTest = readJson(path.join(runDir, EXISTING_TEST_FILE)) as ExistingTest | null
+      // Otherwise: what the repository's tests already cover of this run decides reuse, extend, or new.
+      const chosen = existingTest?.testFile ? { target: undefined } : await chooseTarget(runDir, repo, args, ctx)
+      if ("cancelled" in chosen) return { status: "cancelled", notes: "The user cancelled before Scribe started; nothing was changed." }
+      const target = chosen.target
       ctx.emit?.({ type: "code-start", runDir, repo, goal })
       let r
       try {
@@ -119,6 +192,8 @@ export const COMMAND_TOOLS: McpTool[] = [
           onEvent: (event) => ctx.emit?.({ type: "agent", event }),
           open: ctx.openSession as never,
           runTest: ctx.runTest,
+          ...(existingTest?.testFile ? { existingTest } : {}),
+          ...(target ? { target } : {}),
         })
       } catch (err) {
         ctx.emit?.({ type: "code-done", error: (err as Error).message, ms: Date.now() - t0 })
@@ -136,6 +211,7 @@ export const COMMAND_TOOLS: McpTool[] = [
         notes: r.notes || undefined,
         browsers: r.browsers,
         review: r.review,
+        ...(r.existing ? { existing: r.existing } : {}),
         output: r.status === "passed" ? undefined : clip(r.output, 4000),
       }
     },

package/src/mcp/tools.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs"
 import path from "node:path"
 
 import type { AgentEvent, CodeEvent, CodeResult, ReplayMode, RunResult } from "../types.ts"
@@ -16,6 +16,7 @@ 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 { browserProvider, type AppConfig } from "../config.ts"
 import { clearMemory, memoryFilesFor, memoryFlows, memoryOverview, memoryShow } from "../memory.ts"
 import { executeRun, runDirectory } from "../run.ts"
@@ -329,6 +330,59 @@ function devicesFor(args: Record<string, unknown>, ctx: ToolContext): string[] {
   return [...new Set(devices)]
 }
 
+/**
+ * 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> {
+  const cfg = ctx.config
+  if (!cfg.memory.enabled) return null
+  let repo = ctx.cwd
+  try {
+    repo = realpathSync(ctx.cwd)
+  } catch {}
+  const known = findWrittenTest(cfg.memory.dir, repo, goal, (f) => existsSync(path.resolve(repo, f)))
+  if (!known) return null
+  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,
+    cwd: repo,
+    timeoutSeconds: cfg.code.testTimeoutSeconds,
+    signal: ctx.signal,
+    hide: privateEnvNames(cfg),
+    save: path.join(runDir, "existing-test"),
+  })
+  if (ctx.signal?.aborted) return null
+  const secs = Math.round(run.ms / 1000)
+  if (run.ok && run.browsers.length) {
+    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`],
+      },
+    })
+    return {
+      passed: {
+        status: "passed",
+        reused_test: known.test_file,
+        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.",
+      },
+    }
+  }
+  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` })
+  return { failed: { testFile: known.test_file, command: known.command, output: run.output, why } }
+}
+
 export const TOOLS: McpTool[] = [
   {
     name: "browser_run",
@@ -362,6 +416,11 @@ export const TOOLS: McpTool[] = [
           description:
             "test: a user flow of the app under test, to verify and turn into an automated test. task: anything else done in a browser, such as looking up or linking work items, checking a relationship, or reading data from a tool; no test is written for it.",
         },
+        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.",
+        },
       },
       required: ["goal", "purpose"],
     },
@@ -378,6 +437,10 @@ export const TOOLS: McpTool[] = [
       if (devices.length > 1) return runGoalOnDevices(goal, url, devices, args, ctx)
       const runDir = runDirectory(ctx.config.export.outDir)
       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
+      if (reuse?.passed) return reuse.passed
       const t0 = Date.now()
       emit({ type: "run-start", goal, url })
       try {
@@ -406,7 +469,11 @@ export const TOOLS: McpTool[] = [
           return summary
         }
         if (ctx.writeTests && result.status === "complete" && result.driver !== "synthetic") {
-          return { ...summary, next_step: `This session turns passed runs into tests: call write_test with run_dir ${runDir} now, before you reply.` }
+          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.` : ""}`,
+          }
         }
         return summary
       } catch (err) {

package/src/types.ts

@@ -116,6 +116,8 @@ export type CodeResult = {
   knownDefect?: boolean
   /** The job did not finish: what it wrote was moved to the needs-attention folder (see src/code/attention.ts). */
   attention?: { dir: string; files: string[]; patch?: string; readme: string }
+  /** The job worked from an existing test: ran it as it was, extended it, or updated it. */
+  existing?: "reused" | "extended" | "updated"
 }
 
 /** What an agent did to a file, for the shell's file list. */