@capagents/forgeqe 1.1.8 → 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:
@@ -647,7 +662,22 @@ What happens after the run passes:
 4. It writes the test from the handoff and the replay script: steps that worked are ported with their locators, steps that failed are fixed first. Every locator, including those for assertions, comes from the replay script, the page snapshots, page memory, or a check on the page; steps where the browser agent ran JavaScript to look around are left out. It does not walk the flow again or build tests to explore. Once a step fails (in the replay, or in its test), ForgeQE switches on its live browser: a Chrome that Playwright drives, set up like ForgeQE's, where it looks at the failing step's page one tool call per action (open, snapshot, click, type, wait, screenshot, run JavaScript, console errors, failed requests). Until then the live browser tools are off, so no tokens go into looking at pages that work. The live browser needs Node.js (`npx`), and Microsoft's Playwright MCP server is downloaded on first use; with `live_browser: false`, or without `npx`, it looks with a small throwaway script instead. When its browser gets a different page than ForgeQE's did (an error, a challenge, a control that will not open), it compares the two browsers (user agent, `navigator.webdriver`, headless, failed requests and CORS errors, headers the framework adds, console errors) and fixes the difference in the repo's browser configuration. It never judges the site with `curl` or `webfetch`.
 5. Scribe does not run the test itself: it may build or compile, then reports the test file and the command that runs only that test, and ForgeQE runs it. If one command it runs fails `stall_after` times in a row within its work (the same build again and again, say), ForgeQE stops that turn and sends the command and its last output back, asking it to change approach. If the same command stalls again, the job stops as a failure with that output in the notes.
 6. ForgeQE runs that command (with `CI=1`) and checks the exit code, and it watches the processes the command starts for a browser launched by Playwright, Puppeteer, Selenium, or Cypress. On a failure it sends the command, exit code, and output back to Scribe. The output is kept short so the error is never cut off: the page dump Playwright puts into a failed assertion ("Aria snapshot:", often thousands of lines) is taken out and saved as `<run>/test-runs/attempt-N-page.aria.yml`, then the start (where the first error and its stack trace are) and the end (the summary) are sent; the full output is in `<run>/test-runs/attempt-N.log`, and the prompt names both files. A command that exits 0 without starting a browser also goes back: the test must drive the app in a browser. If the repo's browser runs on another machine (Selenium Grid, a cloud service, a container), the agent says where and the check is skipped.
-7. A passing test then goes to a separate reviewer agent, which can read files and `git diff` but not change anything. It checks the change against the goal and the test rules: every part of the goal done through the page and asserted, generic page objects with data in the test, no values or URLs copied from the run, browser settings in the repo's configuration, no leftover files. The changed files come inline in its prompt, so it reads nothing again, and it does not ask to replace locators or texts that came from the replay or the checks, since those matched the live site. It judges only what this job changed: ForgeQE records the working tree before the job, so your uncommitted edits, your untracked files, and ForgeQE's own files (`.forgeqe/`, `forgeqe.yaml`, `llms.json`) are never part of the review. It checks the diff of every file that existed before the job: removing or rewriting an existing test, even a commented-out one, is a correctness problem. Credentials come from the environment, except a public demo login that the application itself shows to anyone (such as the logins on saucedemo.com's sign-in page), which may stay in the repo's test data. It gets the outlines of the classes the changed code uses, the repo's browser settings, and the same `code_*` tools, so it checks reuse and settings without reading those files. The code graph also tells it what the job added that it can check in the code: a new member that locates an element an existing member already locates (to reuse instead), and new XPath or position-based locators. If it finds problems, they go back to Scribe as the next attempt.
+7. A passing test then goes to a separate reviewer agent, which can read files and `git diff` but not change anything. It checks the change against the goal and the test rules: every part of the goal done through the page and asserted, generic page objects with data in the test, no values or URLs copied from the run, browser settings in the repo's configuration, no leftover files. The changed files come inline in its prompt, so it reads nothing again, and it does not ask to replace locators or texts that came from the replay or the checks, since those matched the live site. It judges only what this job changed: ForgeQE records the working tree before the job, so your uncommitted edits, your untracked files, and ForgeQE's own files (`.forgeqe/`, `forgeqe.yaml`, `llms.json`) are never part of the review. It checks the diff of every file that existed before the job: removing or rewriting an existing test, even a commented-out one, is a correctness problem. Credentials come from the environment, except a public demo login that the application itself shows to anyone (such as the logins on saucedemo.com's sign-in page), which may stay in the repo's test data. It gets the outlines of the classes the changed code uses, the repo's browser settings, and the same `code_*` tools, so it checks reuse and settings without reading those files. The code graph also tells it what the job added that it can check in the code: a new member that locates an element an existing member already locates (to reuse instead), and new XPath or position-based locators. If it finds problems, they go back to Scribe as the next attempt. The terminal shows the exchange as it happens, in order: the reviewer's verdict with its reason and each issue (✗ correctness, ~ coding standard) with the file and the fix it asks for; then why Scribe tries again and what it is fixing (the reviewer's issues, or the test's first error); then what Scribe says it did and which files it changed; then the next verdict:
+
+```
+⏺ Reviewer asked for changes  attempt 1 of 5 · 1 to fix, 1 coding-standard
+  ⎿ The test never checks that the pie chart is shown.
+    ✗ Correctness · tests/PracticeTests.cs: No assertion on the SVG pie chart.
+        Fix: Assert the chart's heading and SVG are visible.
+    ~ Coding standard · tests/PracticeTests.cs: Test data is inline.
+        Fix: Move it to the page object.
+⏺ Scribe tries again · attempt 2 of 5  the reviewer asked for changes
+  ⎿ → tests/PracticeTests.cs: No assertion on the SVG pie chart. — fix: Assert the chart's heading and SVG are visible.
+  ⎿ Scribe (attempt 2): Added the pie chart assertion · changed tests/PracticeTests.cs, Pages/PracticePage.cs
+⏺ Reviewer approved the test  attempt 2 of 5
+```
+
+The Activities panel has one line for each verdict and attempt, and `forgeqe` commands outside the terminal UI print the same blocks.
 
    Scribe cannot edit ForgeQE's files or run folders, and cannot run `git clean`, `git reset --hard`, `git stash`, `git restore`, or `git checkout -- <path>`. If it still removes a file that existed before the job, or reverts your uncommitted edits, ForgeQE puts the file back after that attempt and tells the agent.
 8. The job is done when ForgeQE's run passes with a browser and the reviewer approves. It stops as a failure after `max_attempts` attempts, when the job passes `code.max_tokens`, when the reviewer rejects a passing test twice, if the review cannot finish, when the test fails the same way three times in a row (the same output apart from numbers such as timings and line numbers; the second time, Scribe is told its change did not change the failure and to look at the failing step before changing code), or straight away on an auth, API, or context-limit error from the model.

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:
@@ -1302,13 +1317,23 @@ Acceptance criteria:
 <p>ForgeQE runs that command (with <code>CI=1</code>) and checks the exit code, and it watches the processes the command starts for a browser launched by Playwright, Puppeteer, Selenium, or Cypress. On a failure it sends the command, exit code, and output back to Scribe. The output is kept short so the error is never cut off: the page dump Playwright puts into a failed assertion (&quot;Aria snapshot:&quot;, often thousands of lines) is taken out and saved as <code>&lt;run&gt;/test-runs/attempt-N-page.aria.yml</code>, then the start (where the first error and its stack trace are) and the end (the summary) are sent; the full output is in <code>&lt;run&gt;/test-runs/attempt-N.log</code>, and the prompt names both files. A command that exits 0 without starting a browser also goes back: the test must drive the app in a browser. If the repo's browser runs on another machine (Selenium Grid, a cloud service, a container), the agent says where and the check is skipped.</p>
 </li>
 <li>
-<p>A passing test then goes to a separate reviewer agent, which can read files and <code>git diff</code> but not change anything. It checks the change against the goal and the test rules: every part of the goal done through the page and asserted, generic page objects with data in the test, no values or URLs copied from the run, browser settings in the repo's configuration, no leftover files. The changed files come inline in its prompt, so it reads nothing again, and it does not ask to replace locators or texts that came from the replay or the checks, since those matched the live site. It judges only what this job changed: ForgeQE records the working tree before the job, so your uncommitted edits, your untracked files, and ForgeQE's own files (<code>.forgeqe/</code>, <code>forgeqe.yaml</code>, <code>llms.json</code>) are never part of the review. It checks the diff of every file that existed before the job: removing or rewriting an existing test, even a commented-out one, is a correctness problem. Credentials come from the environment, except a public demo login that the application itself shows to anyone (such as the logins on saucedemo.com's sign-in page), which may stay in the repo's test data. It gets the outlines of the classes the changed code uses, the repo's browser settings, and the same <code>code_*</code> tools, so it checks reuse and settings without reading those files. The code graph also tells it what the job added that it can check in the code: a new member that locates an element an existing member already locates (to reuse instead), and new XPath or position-based locators. If it finds problems, they go back to Scribe as the next attempt.</p>
-<p>Scribe cannot edit ForgeQE's files or run folders, and cannot run <code>git clean</code>, <code>git reset --hard</code>, <code>git stash</code>, <code>git restore</code>, or <code>git checkout -- &lt;path&gt;</code>. If it still removes a file that existed before the job, or reverts your uncommitted edits, ForgeQE puts the file back after that attempt and tells the agent.</p>
-</li>
-<li>
-<p>The job is done when ForgeQE's run passes with a browser and the reviewer approves. It stops as a failure after <code>max_attempts</code> attempts, when the job passes <code>code.max_tokens</code>, when the reviewer rejects a passing test twice, if the review cannot finish, when the test fails the same way three times in a row (the same output apart from numbers such as timings and line numbers; the second time, Scribe is told its change did not change the failure and to look at the failing step before changing code), or straight away on an auth, API, or context-limit error from the model.</p>
+<p>A passing test then goes to a separate reviewer agent, which can read files and <code>git diff</code> but not change anything. It checks the change against the goal and the test rules: every part of the goal done through the page and asserted, generic page objects with data in the test, no values or URLs copied from the run, browser settings in the repo's configuration, no leftover files. The changed files come inline in its prompt, so it reads nothing again, and it does not ask to replace locators or texts that came from the replay or the checks, since those matched the live site. It judges only what this job changed: ForgeQE records the working tree before the job, so your uncommitted edits, your untracked files, and ForgeQE's own files (<code>.forgeqe/</code>, <code>forgeqe.yaml</code>, <code>llms.json</code>) are never part of the review. It checks the diff of every file that existed before the job: removing or rewriting an existing test, even a commented-out one, is a correctness problem. Credentials come from the environment, except a public demo login that the application itself shows to anyone (such as the logins on saucedemo.com's sign-in page), which may stay in the repo's test data. It gets the outlines of the classes the changed code uses, the repo's browser settings, and the same <code>code_*</code> tools, so it checks reuse and settings without reading those files. The code graph also tells it what the job added that it can check in the code: a new member that locates an element an existing member already locates (to reuse instead), and new XPath or position-based locators. If it finds problems, they go back to Scribe as the next attempt. The terminal shows the exchange as it happens, in order: the reviewer's verdict with its reason and each issue (✗ correctness, ~ coding standard) with the file and the fix it asks for; then why Scribe tries again and what it is fixing (the reviewer's issues, or the test's first error); then what Scribe says it did and which files it changed; then the next verdict:</p>
 </li>
 </ol>
+<pre><code>⏺ Reviewer asked for changes  attempt 1 of 5 · 1 to fix, 1 coding-standard
+  ⎿ The test never checks that the pie chart is shown.
+    ✗ Correctness · tests/PracticeTests.cs: No assertion on the SVG pie chart.
+        Fix: Assert the chart's heading and SVG are visible.
+    ~ Coding standard · tests/PracticeTests.cs: Test data is inline.
+        Fix: Move it to the page object.
+⏺ Scribe tries again · attempt 2 of 5  the reviewer asked for changes
+  ⎿ → tests/PracticeTests.cs: No assertion on the SVG pie chart. — fix: Assert the chart's heading and SVG are visible.
+  ⎿ Scribe (attempt 2): Added the pie chart assertion · changed tests/PracticeTests.cs, Pages/PracticePage.cs
+⏺ Reviewer approved the test  attempt 2 of 5
+</code></pre>
+<p>The Activities panel has one line for each verdict and attempt, and <code>forgeqe</code> commands outside the terminal UI print the same blocks.</p>
+<p>Scribe cannot edit ForgeQE's files or run folders, and cannot run <code>git clean</code>, <code>git reset --hard</code>, <code>git stash</code>, <code>git restore</code>, or <code>git checkout -- &lt;path&gt;</code>. If it still removes a file that existed before the job, or reverts your uncommitted edits, ForgeQE puts the file back after that attempt and tells the agent.
+8. The job is done when ForgeQE's run passes with a browser and the reviewer approves. It stops as a failure after <code>max_attempts</code> attempts, when the job passes <code>code.max_tokens</code>, when the reviewer rejects a passing test twice, if the review cannot finish, when the test fails the same way three times in a row (the same output apart from numbers such as timings and line numbers; the second time, Scribe is told its change did not change the failure and to look at the failing step before changing code), or straight away on an auth, API, or context-limit error from the model.</p>
 <p><code>blocked</code> is a last resort. The first time the agent reports that the app blocks it, ForgeQE sends it back to compare its browser with ForgeQE's and fix the difference; only a second blocked report, with what it compared, ends the job as blocked.</p>
 <p>The transcript shows the handover and Scribe's work as it goes; files it writes or edits are marked ✎:</p>
 <pre><code>┃

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capagents/forgeqe",
-  "version": "1.1.8",
+  "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

@@ -0,0 +1,74 @@
+import type { Card } from "../card.ts"
+import type { CodeEvent } from "../types.ts"
+
+/**
+ * The exchange between Scribe and the reviewer, as the shell and the CLI show it: what the reviewer found and why,
+ * why Scribe tries again and what it is fixing, and what Scribe says it did. One place, so both say the same.
+ */
+
+type Review = Extract<CodeEvent, { kind: "review" }>
+type Attempt = Extract<CodeEvent, { kind: "attempt" }>
+type Answer = Extract<CodeEvent, { kind: "answer" }>
+
+const clip = (t: string, n: number) => {
+  const s = t.replace(/\s+/g, " ").trim()
+  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
+  const standards = e.issues.length - correctness
+  const count = [correctness ? `${correctness} to fix` : "", standards ? `${standards} coding-standard` : ""].filter(Boolean).join(", ")
+  return {
+    status: e.approved ? "ok" : "fail",
+    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(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.
+        `${i.kind === "standards" ? "~ Coding standard" : "✗ Correctness"}${i.file ? ` · ${i.file}` : ""}: ${clip(i.problem, 300)}`,
+        ...(i.fix ? [`    Fix: ${clip(i.fix, 300)}`] : []),
+      ]),
+    ],
+  }
+}
+
+/** "Scribe · attempt 2 of 5 · the reviewer asked for changes", then each thing it was asked to fix. */
+export function attemptCard(e: Attempt): Card {
+  return {
+    status: "info",
+    title: `Scribe tries again · attempt ${e.attempt} of ${e.max}`,
+    ...(e.why ? { stats: e.why } : {}),
+    body: e.fixing.map((f) => `→ ${clip(f, 300)}`),
+  }
+}
+
+/** "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(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

@@ -38,6 +38,8 @@ import {
   standardsFixPrompt,
   type AgentReport,
   type ExistingTest,
+  type ReviewIssue,
+  type TestTarget,
 } from "./prompt.ts"
 import { openReviewer, type Reviewer } from "./review.ts"
 import { runTestCommand } from "./testrun.ts"
@@ -80,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)
@@ -115,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}`)
@@ -254,6 +296,9 @@ export async function runCodeAgent(opts: {
   let spent: Usage = { input: 0, output: 0 }
   const attemptLog: string[] = []
   let nextTask: string | null = null
+  /** Why the next attempt runs and what it is to fix, as the shell shows it: "the reviewer asked for changes", its issues. */
+  let next: { why: string; fixing: string[] } = { why: "", fixing: [] }
+  const issueText = (i: ReviewIssue) => `${i.file ? `${i.file}: ` : ""}${i.problem}${i.fix ? ` — fix: ${i.fix}` : ""}`
   let notesText: string | undefined = known ? notesSection(known) : undefined
   // The repository's test setup, read by ForgeQE without a model; Scribe starts from it instead of a reading turn.
   const repoProfile = buildProfile(repo)
@@ -330,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()
@@ -374,7 +419,7 @@ export async function runCodeAgent(opts: {
         session = await (opts.open || openSession)(sessionOptions())
         result.sessionId = session.sessionId
         saveSession()
-        emit({ type: "code", kind: "info", text: `Scribe starts attempt ${attempt} in a fresh session, from a summary of the job so far` })
+        emit({ type: "code", kind: "attempt", attempt, max: allowed, why: next.why, fixing: next.fixing })
         prompt = nextAttemptPrompt({
           handoff,
           notes: [profileText, notesText].filter(Boolean).join("\n\n") || undefined,
@@ -417,6 +462,8 @@ export async function runCodeAgent(opts: {
         break
       }
       if (reply.report) report = { ...report, ...reply.report }
+      // What Scribe says it did this time, so a retry is not only "Editing …" lines.
+      if (reply.report && (reply.report.notes || reply.report.changed?.length)) emit({ type: "code", kind: "answer", attempt, ...(reply.report.notes ? { notes: reply.report.notes } : {}), changed: reply.report.changed || [] })
       result.notes = report.notes || reply.text.slice(0, 500)
       if (reply.error && FATAL_ERRORS.some((name) => reply.error!.startsWith(name))) {
         result.notes = reply.error
@@ -477,6 +524,7 @@ export async function runCodeAgent(opts: {
         emit({ type: "code", kind: "test", ok: false, attempt, text: `${report.test_file} exited 0 in ${secs}s but opened no browser (attempt ${attempt}/${maxAttempts})` })
         attemptLog.push(attemptLine(attempt, "exited 0 but opened no browser", "", report.notes))
         nextTask = noBrowserPrompt(report.command)
+        next = { why: "the test passed without opening a browser", fixing: ["Make the test drive a real browser, as the run did"] }
         continue
       }
       if (run.ok) {
@@ -488,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
@@ -501,6 +549,8 @@ export async function runCodeAgent(opts: {
         result.review = verdict.review
         const correctness = verdict.review.issues.filter((i) => i.kind !== "standards")
         const standards = verdict.review.issues.filter((i) => i.kind === "standards")
+        // The verdict as the reviewer gave it: with only coding-standard issues the test is approved and gets a tidy-up.
+        emit({ type: "code", kind: "review", attempt, max: allowed, approved: verdict.review.approved || !correctness.length, summary: verdict.review.summary, issues: verdict.review.issues })
         // Coding standards alone never fail a test that works and tests the goal.
         if (tidying && correctness.length) {
           // The tidy-up changed what the test does: back to the version that passed.
@@ -515,9 +565,13 @@ export async function runCodeAgent(opts: {
             emit({ type: "code", kind: "test", ok: true, attempt, text: `${report.test_file} passed and tests the goal; the reviewer found ${standards.length} coding-standard ${standards.length === 1 ? "issue" : "issues"}, so the agent fixes ${standards.length === 1 ? "it" : "them"} in one more round (the passing version is kept if that breaks it)` })
             attemptLog.push(attemptLine(attempt, "passed and tests the goal; coding-standard issues to fix", standards.map((i) => i.problem).join(" "), report.notes))
             nextTask = standardsFixPrompt(standards)
+            next = { why: "the reviewer approved the test; one round for its coding-standard issues", fixing: standards.map(issueText) }
             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(" ")}`
@@ -526,8 +580,7 @@ export async function runCodeAgent(opts: {
           emit({ type: "code", kind: "test", ok: true, attempt, text: `${report.test_file} passed and was approved (attempt ${attempt}/${allowed})${standards.length ? `; ${standards.length} coding-standard ${standards.length === 1 ? "issue" : "issues"} left in the notes` : ""}` })
           break
         }
-        const n = verdict.review.issues.length
-        emit({ type: "code", kind: "test", ok: false, attempt, text: `review found ${n} ${n === 1 ? "issue" : "issues"}: ${verdict.review.summary} (attempt ${attempt}/${maxAttempts})` })
+        // The review event above says what was found; the rejection itself is its verdict.
         // A second rejection usually means the goal and the page disagree (a test case the page cannot satisfy), not a
         // fix the next attempt will find: stop and report the issues instead of spending the remaining attempts.
         if (++rejections >= MAX_REJECTIONS) {
@@ -537,12 +590,20 @@ export async function runCodeAgent(opts: {
         }
         attemptLog.push(attemptLine(attempt, "passed; the reviewer asked for changes", verdict.review.summary, report.notes))
         nextTask = reviewFixPrompt(verdict.review.summary, verdict.review.issues)
+        next = { why: "the reviewer asked for changes", fixing: verdict.review.issues.map(issueText) }
         continue
       }
       if (tidying) {
         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(", ")}` })
@@ -555,14 +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: 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: failureReason(run.output) }
     }
     keepSession = result.status === "stopped" || runtimeFailed
     if (report.test_name) result.testName = report.test_name