@capagents/forgeqe 1.2.0 → 1.3.0

package/docs/user-guide.html

@@ -378,7 +378,7 @@ forgeqe docs --copy ./docs   # copy the guide, the architecture page, and the re
 <h3 class="band-title">Every feature</h3>
 <div class="area"><a class="area-name" href="#area-browser"><span class="mono">Browser</span></a><ul class="tiles"><li><a class="tile" href="#cap-browser-goals"><b>Run any goal in a real browser</b><span>Go to booking.com and search hotels in Mumbai for next weekend</span></a></li><li><a class="tile" href="#cap-logins"><b>Saved logins for the application under test</b><span>Sign in to the admin site and keep the session</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-test-cases"><span class="mono">Test cases</span></a><ul class="tiles"><li><a class="tile" href="#cap-run-test-cases"><b>Run manual test cases in browsers</b><span>Run SHOP-12 and SHOP-14 from Jira, two browsers at once</span></a></li><li><a class="tile" href="#cap-test-case-quality"><b>Check and improve test cases</b><span>Are the cases in test plan 12 good enough to run?</span></a></li><li><a class="tile" href="#cap-write-test-cases"><b>Write test cases from a story</b><span>Write test cases for story 1234 and save them</span></a></li><li><a class="tile" href="#cap-domain-compliance"><b>Domain and regulatory test design</b><span>Write test cases for story 1234, covering our DORA and PSD2 obligations</span></a></li><li><a class="tile" href="#cap-exploratory-testing"><b>Exploratory testing of a story</b><span>Explore story 1234 and find bugs</span></a></li></ul></div>
-<div class="area"><a class="area-name" href="#area-automated-tests"><span class="mono">Automated tests</span></a><ul class="tiles"><li><a class="tile" href="#cap-write-tests"><b>Turn a passed run into an automated test</b><span>Write a Playwright test for that run in ../app</span></a></li><li><a class="tile" href="#cap-heal-tests"><b>Heal failing tests</b><span>Heal the failing tests in ../app</span></a></li><li><a class="tile" href="#cap-find-run-tests"><b>Find and run existing tests</b><span>Run the checkout tests</span></a></li><li><a class="tile" href="#cap-flaky-tests"><b>Flaky test detection and quarantine</b><span>Which tests are flaky?</span></a></li></ul></div>
+<div class="area"><a class="area-name" href="#area-automated-tests"><span class="mono">Automated tests</span></a><ul class="tiles"><li><a class="tile" href="#cap-write-tests"><b>Turn a passed run into an automated test</b><span>Write a Playwright test for that run in ../app</span></a></li><li><a class="tile" href="#cap-heal-tests"><b>Heal failing tests</b><span>Heal the failing tests in ../app</span></a></li><li><a class="tile" href="#cap-find-run-tests"><b>Find and run existing tests</b><span>Run the checkout tests</span></a></li><li><a class="tile" href="#cap-regression-packs"><b>Regression packs for a release</b><span>Build a regression pack for sprint 12 and run it on TestMu</span></a></li><li><a class="tile" href="#cap-flaky-tests"><b>Flaky test detection and quarantine</b><span>Which tests are flaky?</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-pull-requests"><span class="mono">Pull requests</span></a><ul class="tiles"><li><a class="tile" href="#cap-pr-review"><b>Review pull requests</b><span>Review PR 42 and focus on error handling</span></a></li><li><a class="tile" href="#cap-pr-impact"><b>Pull request impact and test selection</b><span>What does PR 42 impact?</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-api"><span class="mono">API</span></a><ul class="tiles"><li><a class="tile" href="#cap-api-testing"><b>API and contract testing</b><span>Turn the last run's API calls into tests</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-quality"><span class="mono">Quality</span></a><ul class="tiles"><li><a class="tile" href="#cap-accessibility-performance"><b>Accessibility and page performance</b><span>Is the checkout page accessible?</span></a></li><li><a class="tile" href="#cap-visual-comparison"><b>Visual comparison with baselines</b><span>What changed visually since the last run?</span></a></li><li><a class="tile" href="#cap-defect-intelligence"><b>Defect intelligence: trends and prediction</b><span>Which defects keep coming back?</span></a></li></ul></div>
@@ -590,6 +590,7 @@ forgeqe auth logout jira
 </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>When the flow cannot be reproduced.</strong> If ForgeQE's own replay of the run could not reach the run's final page and Scribe's first test fails too, the job stops there and says which replayed step failed and why, instead of spending its remaining attempts on a flow no script can repeat as recorded.</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>
@@ -917,6 +918,17 @@ forgeqe memory clear booking.com --yes
 <h4>Test cases and suites</h4>
 <div class="prose"><p>Test cases you already have can be run two ways. In the shell or with <code>forgeqe run</code>, ask in plain words (&quot;run SHOP-12 and SHOP-14&quot;, &quot;run test plan 12 suite 34&quot;, &quot;run the cases in smoke.yaml&quot;) or paste the cases, and the agent works out the source. <code>forgeqe suite</code> takes explicit references and runs the same way every time, with no agent involved, which is what pipelines call. Each case is one goal: ForgeQE tells the agent to do the steps in order and to check every expected result, and the agent's verdict decides whether the case passed. A case with no steps (plain text, a Jira story) is run from its description.</p>
 </div>
+<section class="doc sub" id="doc-how_to_use-api-steps-in-a-test-case"><h5>API steps in a test case</h5><div class="prose"><p>A test case can mix API and UI steps (&quot;add three products with POST /add_to_cart/{id}, then remove the first one in the cart, then pay&quot;). The browser agent makes each API step with its <code>api_request</code> action, from the page, in the browser's own session: the logged-in user's cookies go with the call, and the CSRF token comes from the cookie or the page's form when the site needs one. So what an API step changes (a cart, an order) is what the next UI step sees.</p>
+<ul>
+<li><strong>The verdict</strong> of an API step rests on the status the server answered, not on the agent's account of it.</li>
+<li><strong>The run records it</strong> as an <code>api</code> step in <code>workflow.yaml</code>: method, URL, body, CSRF source, and the status and final URL the server gave.</li>
+<li><strong>ForgeQE's replay repeats it</strong> the same way, and fails that step when the server answers differently (403 where the run got 200), so the replay and the test get past it instead of stalling on an empty cart.</li>
+<li><strong>Scribe's handoff</strong> lists each API step with what was sent and answered, and tells Scribe to make it through the framework's API request context that shares the browser's cookies (Playwright's <code>page.request</code>), asserting the status.</li>
+<li><strong>Kept for reuse</strong>: the calls are saved as an API scenario, one per test case (<code>out/api/case-ado-2287/</code>, updated by each run), which <code>forgeqe api</code> and the API tools run again without a browser. The run's card says where (<em>API  2 calls saved as a reusable API scenario</em>).</li>
+</ul>
+<p>URLs the case gives are opened exactly as given: when the model adds a trailing slash (<code>/login/</code>, a 404 on many sites), ForgeQE opens and records the URL from the case.</p>
+<p>When a run finds a test case does not fit the application, the agent drafts the steps as they should be, from what the run found, and offers to save them. <code>update_test_case</code> shows the current and the new steps and asks before it changes the Azure DevOps Test Case; the reason goes into the work item's history, where the old steps stay.</p>
+</div></section>
 <section class="doc sub" id="doc-how_to_use-when-a-case-fails"><h5>When a case fails</h5><div class="prose"><p>The browser run of a test case is the test, so when a case does not pass, ForgeQE works out what kind of failure it was and acts on it. The browser agent reports a cause for each failed step (it saw the page); clear evidence in the run, such as an unreachable site or a 503 page, overrides &quot;I could not operate it&quot;.</p>
 <div class="tbl"><table>
 <thead>
@@ -1115,10 +1127,10 @@ forgeqe suite cases.yaml --no-code --no-write-back --out .forgeqe/reports/smoke
 </article>
 <article class="spec feat" id="cap-test-case-quality">
 <div class="hd"><span class="mono">Test cases</span><h3>Check and improve test cases</h3></div>
-<p class="ds">Checks test cases before they run (vague or missing expected results, missing test data, placeholders, duplicates) against the story, feature, and epic they test, then rewrites Azure DevOps cases once the user agrees.</p>
+<p class="ds">Checks test cases before they run (vague or missing expected results, missing test data, placeholders, duplicates) against the story, feature, and epic they test, then rewrites Azure DevOps or Jira cases in place once the user agrees.</p>
 <div class="facts">
 <div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Are the cases in test plan 12 good enough to run?</li><li>Fix the expected results of case 4512</li></ul></div>
-<div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need opt">Optional</span><span>Azure DevOps, to rewrite cases in place: set up under sources: in forgeqe.yaml, or sign in with /auth</span></li></ul></div>
+<div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need opt">Optional</span><span>Azure DevOps or Jira, to rewrite cases in place: set up under sources: in forgeqe.yaml, or sign in with /auth</span></li></ul></div>
 <div class="fact"><span class="mono">Tools</span><p class="tools"><code>check_test_cases</code> <code>update_test_case</code></p></div>
 </div>
 <div class="detail"><span class="mono">In detail</span>
@@ -1148,19 +1160,18 @@ forgeqe suite cases.yaml --no-code --no-write-back --out .forgeqe/reports/smoke
 #   command: [&quot;python&quot;, &quot;rag/search.py&quot;]
 </code></pre>
 <p>The answer can also be an object with <code>results</code>, <code>passages</code>, <code>documents</code>, or <code>hits</code>, and a passage's text can be <code>text</code>, <code>content</code>, or <code>page_content</code> (LangChain's shape). A RAG server with an MCP interface works through <code>mcp:</code> instead: ForgeQE's agent calls its tools.</p>
-<p><code>suite.case_check</code> decides what happens before a run: <code>warn</code> (the default) shows the findings and runs every case, <code>block</code> leaves out the cases that cannot run as written, <code>off</code> skips the check.</p>
-<p>When a run finds a test case does not fit the application, the agent drafts the steps as they should be, from what the run found, and offers to save them. <code>update_test_case</code> shows the current and the new steps and asks before it changes the Azure DevOps Test Case; the reason goes into the work item's history, where the old steps stay.</p>
+<p><code>suite.case_check</code> decides what happens before a run: <code>warn</code> (the default) shows the findings and runs every case, <code>block</code> leaves out the cases that cannot run as written, <code>off</code> skips the check. Ask to run a case and it runs, whatever the check found; ForgeQE's agent reports the findings with the result instead of refusing. A case whose steps have no expected results runs too: it passes when every step can be done, and the check lists it <strong>to review</strong>, since it checks no result the page should show.</p>
 </div>
 </section>
 </div>
 </article>
 <article class="spec feat" id="cap-write-test-cases">
 <div class="hd"><span class="mono">Test cases</span><h3>Write test cases from a story</h3></div>
-<p class="ds">Writes test cases from a story's acceptance criteria and saves them in Azure DevOps or Jira, linked to the story.</p>
+<p class="ds">Writes test cases from a story's acceptance criteria and saves them in Azure DevOps or Jira, linked to the story. Reads the cases already linked first, so asking again adds only what is missing and updates cases in place instead of duplicating them; plans end-to-end journeys from the existing cases.</p>
 <div class="facts">
-<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Write test cases for story 1234 and save them</li></ul></div>
+<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Write test cases for story 1234 and save them</li><li>Build an end-to-end journey from story 1234's cases</li></ul></div>
 <div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need req">Required</span><span>Azure DevOps or Jira: set up under sources: in forgeqe.yaml, or sign in with /auth</span></li></ul></div>
-<div class="fact"><span class="mono">Tools</span><p class="tools"><code>save_test_cases</code></p></div>
+<div class="fact"><span class="mono">Tools</span><p class="tools"><code>story_test_cases</code> <code>save_test_cases</code> <code>e2e_journey</code></p></div>
 </div>
 <div class="detail"><span class="mono">In detail</span>
 <p class="see">See <a href="#doc-how_to_use-where-cases-come-from">Where cases come from</a>.</p>
@@ -1491,6 +1502,53 @@ Run the tests added since 2026-09-01
 </section>
 </div>
 </article>
+<article class="spec feat" id="cap-regression-packs">
+<div class="hd"><span class="mono">Automated tests</span><h3>Regression packs for a release</h3></div>
+<p class="ds">Builds a regression pack from what goes into a release (an Azure DevOps sprint or work items, a commit range, pull requests, or changes read from any connected tool): the tests those changes can break, each with why, plus risk-area and smoke tests, and the changes no test covers. Runs it locally, on TestMu AI, or in a pipeline, and compares each run with the last.</p>
+<div class="facts">
+<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Build a regression pack for sprint 12 and run it on TestMu</li><li>Which tests should we run for the PRs merged this week?</li></ul></div>
+<div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need input">You give</span><span>a repository with tests</span></li><li><span class="need opt">Optional</span><span>Azure DevOps or Jira, to read a sprint's or release's work items: set up under sources: in forgeqe.yaml, or sign in with /auth</span></li></ul></div>
+<div class="fact"><span class="mono">Tools</span><p class="tools"><code>build_regression_pack</code> <code>run_regression_pack</code> <code>list_regression_packs</code></p></div>
+</div>
+<div class="detail"><span class="mono">In detail</span>
+<section class="doc" id="doc-how_to_use-regression-packs-for-a-release">
+<h4>Regression packs for a release</h4>
+<div class="prose"><p>A regression pack is the set of your repository's tests that a release's changes can break, saved under a name so you can run it again (here, on TestMu AI, or in a pipeline) and compare runs. Ask in your own words:</p>
+<pre><code class="language-text">Build a regression pack for sprint 12 and run it on TestMu
+Which tests should we run for the PRs merged this week?
+Build a pack for Jira fix version 2.4 and the commits since release/2.3 in ../shop-app
+</code></pre>
+<p><strong>Where the changes come from.</strong> Any mix of:</p>
+<ul>
+<li>an Azure DevOps sprint, area, epic or feature, or work item ids: their stories and bugs, the test cases each is tested by, and the files their linked pull requests changed;</li>
+<li>the commits between two refs of a repository (<code>from</code> and <code>to</code>): the product's repository, or the test repository's own; work items the commit messages name (<code>AB#123</code>, <code>#123</code>, <code>PAY-12</code>) are read too;</li>
+<li>pull requests by number or URL, or the ones merged in the last N days (Azure DevOps or GitHub);</li>
+<li>anything ForgeQE's agent can read through its connected tools (a Jira release, GitHub issues, a Confluence release note): it reads the items and passes them in with their text and links.</li>
+</ul>
+<p><strong>Why each test is in.</strong> A test can be in for more than one reason, and the card and <code>&lt;name&gt;.md</code> say each one:</p>
+<div class="tbl"><table>
+<thead>
+<tr><th>Reason</th><th>Meaning</th></tr>
+</thead>
+<tbody>
+<tr><td>linked</td><td>it automates a test case that tests a changed work item (<code>.forgeqe/test-cases.json</code>, or a case id in the test's attributes)</td></tr>
+<tr><td>test code changed</td><td>the change is in the test repository, in code the test uses</td></tr>
+<tr><td>matches a change</td><td>the work item's or pull request's words name what the test does: the elements it uses, its page, its name</td></tr>
+<tr><td>risk area</td><td>the release touches an area with defects or failures before, and the test works there</td></tr>
+<tr><td>smoke</td><td>the test is tagged smoke, so it is in every pack</td></tr>
+</tbody>
+</table></div>
+<p><strong>Gaps.</strong> Changes no test is in for are listed as <em>not covered</em>, each with the closest existing test and what it lacks, so you can extend that test rather than write a new one.</p>
+<p><strong>Running it.</strong> ForgeQE asks before it runs anything.</p>
+<ul>
+<li><em>This machine</em>: ForgeQE builds one command for exactly the pack's tests, the way the repository already runs a test (for .NET, a <code>--filter</code> with each test, the settings an earlier job used, TRX results), runs it, and reads each result. A failed test runs once more; one that then passes is flaky.</li>
+<li><em>TestMu AI</em>: the same command, with the variable <code>FORGEQE_PW_WS_ENDPOINT</code> set to TestMu AI's Playwright endpoint for the browser and platform in <code>testmu.yaml</code> (the access key goes in the variable, never in the command, and is removed from the output). The tests must connect to it when it is set: for NUnit, override <code>ConnectOptionsAsync</code> in the test base class; for Playwright Test, set <code>connectOptions</code> from it in <code>playwright.config</code>. ForgeQE refuses a TestMu run when the tests do not read the variable, so a run never looks remote while it ran locally.</li>
+</ul>
+<p>Each run is kept with the pack: the card says which tests fail now that passed in the last run, and which were fixed. Packs are saved in <code>.forgeqe/packs/&lt;name&gt;.json</code> and <code>&lt;name&gt;.md</code>; run output and results in <code>.forgeqe/reports/packs/&lt;name&gt;/&lt;time&gt;/</code>.</p>
+</div>
+</section>
+</div>
+</article>
 <article class="spec feat" id="cap-flaky-tests">
 <div class="hd"><span class="mono">Automated tests</span><h3>Flaky test detection and quarantine</h3></div>
 <p class="ds">Finds tests that flip between passing and failing in the repository's run history, with their likely cause, and quarantines them once the user agrees.</p>

package/forgeqe.example.yaml

@@ -75,6 +75,13 @@ memory:
   dir: ./.forgeqe/memory # pages, elements, locators, and recorded flows
   replay: verify # verify | trust | off
 
+# Cost-aware execution (docs/COST_ARCHITECTURE.md), on by default. on: a rerun of a passed run (the rerun link,
+# /rerun, "run it again", the same goal word for word) runs as recorded without the agent, and a replay whose
+# recorded checks all hold passes with no model; anything else, or any check that fails, goes to the agent.
+# shadow: only records what it would have done (.forgeqe/registry). off: every request goes to ForgeQE's agent.
+registry:
+  mode: on # on | shadow | off
+
 code:
   # repo: ../my-app          # where passed runs become tests (default: the current folder; --no-code turns it off)
   # test_command: npx playwright test   # the repo's test command, for forgeqe heal; default: the agent finds it
@@ -114,6 +121,14 @@ report:
   screenshots: all            # all | failures | off: step screenshots in report.html
   accessibility: true         # check each page the agent visits (names, labels, image text, contrast, lang, zoom)
 
+# Model spending budgets, in the price currency. They only warn (at 80%, 90% and 100%) and never stop a run.
+# Day and month (UTC) count every ForgeQE process on this machine, from the usage ledger in ~/.forgeqe/usage.
+# budget:
+#   run: 2          # one browser run
+#   day: 25
+#   month: 400
+#   # currency: USD # default: the currency of the model's price
+
 # Offline BI with Evidence: ForgeQE exports CSV datasets and runs Evidence (@evidence-dev/evidence 40.x, needs Node.js)
 # to build a static site, no always-on server. forgeqe bi init scaffolds the Evidence project, forgeqe bi sync refreshes
 # the data, forgeqe bi build does both and builds the site; without Node.js, or with --static, it writes ForgeQE's own

package/package.json

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

@@ -26,9 +26,11 @@ A message can also be a task specification with the parts Role, Objective, Conte
 **Tools** (ForgeQE tools; the client adds the forgeqe_ prefix):
 - browser_run: does one goal in a real browser, and verifies it. Use it for all work on a website. Set purpose to test for a flow of the application under test. Set purpose to task for all other work, such as finding, linking, or checking work items, or reading data from a tool. A task never becomes an automated test.
 - find_test_cases: reads test cases from Azure DevOps, Jira, Xray, TestRail, Zephyr Scale, qTest, GitHub issues, files, or text. It does not run them.
-- save_test_cases: saves test cases that you wrote from a story into Azure DevOps (Test Case work items) or Jira, linked to the story. It gives a link for each case.
+- story_test_cases: gives the test cases already linked to an Azure DevOps or Jira story, with their steps. It changes nothing.
+- save_test_cases: saves test cases that you wrote from a story into Azure DevOps (Test Case work items) or Jira, linked to the story. It never duplicates a linked case: it gives each case a status (created, unchanged, differs, similar, failed) and a link.
 - check_test_cases: checks test cases before they run. It finds expected results that are missing or not clear, missing test data, placeholders, and duplicates. It runs nothing.
-- update_test_case: writes the steps of an Azure DevOps Test Case again, after the user agrees. It asks the user.
+- update_test_case: writes the steps of an Azure DevOps Test Case or a Jira test issue again, in place, after the user agrees. It asks the user.
+- e2e_journey: plans end-to-end journeys from test cases that exist (the cases of a story, or any sources). It keeps the steps they share once, and gives each case as a section. It changes nothing.
 - release_readiness: gives requirement coverage and a GO / GO WITH RISKS / NO-GO verdict for a sprint, area, epic, or stories. It uses test cases, their results, bugs, and flaky tests. It can publish to the wiki. Examples: "are we ready to release?", "coverage of sprint 12".
 - run_test_cases: runs test cases in real browsers, with a verdict for each step. It writes report.html (steps, screenshots, timings) and junit.xml. It sends results back to the source system. It files or updates bugs for failures when bugs are set up. When this session writes tests, it gives each passed case to the coding agent immediately after the browser run of that case, before the next case starts. It gives the test of each case.
 - read_confluence: reads Confluence pages (requirements, specifications) as text, by id, link, or CQL.
@@ -43,6 +45,9 @@ A message can also be a task specification with the parts Role, Objective, Conte
 - flaky_tests: gives the flaky tests from that history, with their probable cause.
 - defect_trends: gives how the defects of the saved suites went over time: still there, gone, or back after a fix, the time to fix, the most seen, and defects by area. It runs nothing.
 - predict_defects: gives the areas where a change in the product repository can cause defects, with the reasons and the cases to run first. It is a heuristic from the history. It runs nothing.
+- build_regression_pack: builds a regression pack for a release from an Azure DevOps sprint or work items, a commit range, pull requests, or changes you read from other connected tools: the tests the changes can break, each with why, and the changes no test covers. It runs nothing.
+- run_regression_pack: runs a saved pack after the user confirms, on this machine, on TestMu AI, or in a pipeline, and compares the run with the last one.
+- list_regression_packs: gives the saved packs and their last runs.
 - quarantine_tests: puts flaky tests in quarantine, or takes them out, after the user agrees. The failures of a test in quarantine do not fail runs or CI.
 - review_pull_request: Scribe reviews an Azure DevOps or GitHub pull request from the local clone (bugs, security, requirements, tests). The user sees the findings. It posts nothing.
 - post_pr_review: posts a review_pull_request review to the pull request after the user confirms.
@@ -160,10 +165,12 @@ Read data from Azure DevOps, Jira, Xray, Confluence, and other systems in this s
 - run_test_cases files bugs for failed cases itself when "This session" says so, only for functional defects. You MUST NOT file them again. Its write_back list names each bug.
 - run_test_cases checks the cases first (case_check in its result). When a case needs a review or cannot run as written, say so briefly, with the correction.
 - When the user asks if cases are good, ready, clear, or complete, you MUST call check_test_cases.
+- When the user asks to run cases, you MUST call run_test_cases, also when check_test_cases or its card found problems. run_test_cases skips a case only when the setup says so (suite.case_check: block). You MUST NOT refuse a run because of a check verdict. Report what the check found with the result, and offer to fix the case with update_test_case.
 - check_test_cases also reads what each case tests: the story, the feature, the epic, linked Confluence pages, the RAG service, and page memory.
 - You MUST judge each case against that. Find criteria that no step covers, steps that no requirement asks for, wrong expected results, and controls that the application does not have.
 - For a case classified "test case needs updating", you MUST write the correct steps from run_details. Show them, and offer update_test_case.
 - You MUST NOT change a test case without update_test_case, which asks the user first.
+- When the user reviews a saved case and asks for a change, you MUST call update_test_case with the id of that case. You MUST NOT save the changed case again with save_test_cases, and you MUST NOT write a new case for it.
 - To link cases to a story, or to check a link, you MUST use the MCP tools or query_api, not the browser. When the browser is the only way, call browser_run with purpose task.
 - A browser run of a test case is the test. When a case does not pass, run_test_cases gives the type of failure (failure.type). You MUST report each failed case by that type, in plain words:
   - A functional defect: the application is wrong. Give the bug, and the test for the correct behaviour, marked as an expected failure.
@@ -182,17 +189,27 @@ Domain applies when you write and check test cases, test from requirements, do e
 ### Testing from requirements
 For a Confluence page, a Jira or Azure DevOps story, or a specification file:
 - You MUST read the requirements with read_confluence or the Confluence MCP tools, the MCP tools of the story or query_api, or the file.
+- For an Azure DevOps or Jira story, you MUST call story_test_cases before you write a case. Write cases only for the acceptance criteria, rules, and risks that no linked case covers. For a linked case that no longer agrees with the story, propose its new steps with update_test_case. You MUST NOT write a linked case again. When the linked cases cover everything, say so and write nothing.
 - You MUST write one case for each acceptance criterion or rule, and the main negative paths.
 - You MUST then write one case for each domain risk and obligation on your list that the story does not cover.
 - Each case MUST have a title, the start page when you know it, and numbered steps with an expected result, specific enough for a browser.
 - When the story is in Azure DevOps or Jira, and "This session" says that ForgeQE saves cases there, you MUST save them with save_test_cases before they run.
 - Give save_test_cases the system, the story, and each case with its steps and expected results. You MUST NOT create the cases with the MCP tools or the browser.
-- In the reply, you MUST list each saved case as a markdown link to its work item, with its title, and without its full steps.
+- save_test_cases writes nothing for a case with status differs or similar. You MUST NOT say that such a case was saved or updated. Show how it differs from linked_case, and offer update_test_case. Use force_new only when the user says that it is a different case.
+- In the reply, you MUST list each saved case as a markdown link to its work item, with its title and its status, and without its full steps.
 - When ForgeQE does not save cases there, or the user says not to, you MUST show them as a short markdown list with numbered titles, steps, and expected results.
 - You MUST then run them with run_test_cases, unless the user asked only for the cases.
 - You MUST run saved Azure DevOps cases by their ids (save_test_cases gives run_with), so that the results go back. Run other cases as text sources, one entry for each case.
 - You MUST save cases from other requirements into a test management system only when the user asks. Use save_test_cases when there is a story to link them to. Give the new ids as links.
 
+### End-to-end journeys from test cases
+For "an end-to-end test for story 1234", "combine these cases into one flow", or "E2E from the test plan":
+- You MUST build on the cases that exist. Call e2e_journey with the story, or with the sources. You MUST NOT write the cases again first.
+- When the story has no linked cases yet, write and save them by "Testing from requirements" first, then call e2e_journey.
+- Order the sections so that each one leaves the application in the state that the next one needs. A negative section goes last, or stays its own case.
+- Show each journey with the cases that it covers. When the user agrees, save it with save_test_cases as one case titled "E2E: …", with a description that names the cases it covers. Keep the original cases.
+- For end-to-end API scenarios, use api_scenarios.
+
 ### Signing in
 - The browser agent signs in to the sites under "Saved logins" with stored credentials and a saved session. You MUST NOT ask the user for those passwords or codes.
 - You MUST NOT put credentials in goals.
@@ -217,10 +234,25 @@ For a Confluence page, a Jira or Azure DevOps story, or a specification file:
 - You MUST name the files that it made: report.html in the run folder, and the test that write_test wrote. Say if the run of that test passed. When ForgeQE wrote no test, say so and why.
 - When the user wants logs or details to share for debugging, tell them to type /logs, and add shots for screenshots. Outside the shell, forgeqe logs bundle writes one archive with secrets replaced.
 
+### Regression packs
+When the user asks for a regression pack, or which tests to run for a release, a sprint, or recent pull requests:
+- You MUST give build_regression_pack every source the user names. Give an Azure DevOps sprint, area, epic, or work items directly. Give a commit range as from and to, with range_repo when it is the product repository. Give pull requests as prs or merged_days.
+- When the changes are in another connected tool (a Jira release or fix version, GitHub issues, a release note in Confluence), you MUST read them with that tool first. Then you MUST pass each one in items with its id, title, text, url, and the test cases and work items it links to. You MUST NOT shorten their text: the words find the tests.
+- You MUST report the tests by why they are in, the changes no test covers with the closest test for each, and the risk areas.
+- When the user did not say where to run the pack, you MUST ask one question: on this machine, on TestMu AI, or in a pipeline. You MUST NOT run a pack until the user agrees.
+- After a run, you MUST name the failing tests with their messages, and the tests that fail now but passed in the last run.
+
 ### 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.
+- 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 step or a check that written_for does not have, you MUST call browser_run again with existing_test set to reused_test and existing_mode extend. 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.
+- Before a browser run for a test, browser_run searches the tests of the repository. When some are close to the request but not the same flow, it returns status existing_tests_found and does not start the browser. For each test it gives its steps, the elements of the request that it covers and lacks, and written_for when an earlier job wrote it. You MUST compare them with the request of the user before any browser run. Then you MUST call browser_run again with the same goal and one of these:
+  - existing_test (the test, Class.Method) and existing_mode reuse, when that test already does and checks everything the request asks.
+  - existing_mode extend, when the test covers the start of the journey and the request adds a few steps or checks to it.
+  - existing_mode sibling, when the request is a variant of the test: another path, other data, more than a few added steps, or a test that is long already. A new test goes beside it in its class and reuses its setup and steps.
+  - fresh set to true, when no test is this journey. The new test still reuses the page objects and helpers of the repository.
+  When existing_tests_found has sent_as task, you sent a check of the application as a task, and tests of the repository are close to it. When one of them does what the check asks, you MUST answer the check with it: call browser_run again with the same goal and purpose, existing_test set to that test, and existing_mode reuse. When the user asked for a test, you MUST use purpose test and one of the choices above. You MUST set fresh to true only when no test does what the check asks, or when the check needs data that a passing test does not give, such as a value to read.
+  You MUST NOT write a new test file for a journey that an existing test covers in part. After extend or sibling, write_test does what you chose. You MUST NOT give it a mode.
 - 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.

package/prompts/browser-api.md

@@ -0,0 +1,13 @@
+---
+name: browser-api
+description: "How the browser agent makes the API steps of a test case, in the browser's session, so they are recorded and repeated."
+used_by: "the browser agent (every browser run)"
+kind: fragment
+---
+## API steps
+- For a step that calls an API (an HTTP method, an endpoint, or a payload), you MUST use api_request. You MUST NOT call fetch or XMLHttpRequest from evaluate.
+- Before the first api_request, you MUST open a page of the site. api_request runs in the browser's session and sends its cookies.
+- When the site needs a CSRF token, you MUST set csrf to "cookie" or "form". Use "cookie" for a csrftoken or XSRF-TOKEN cookie, and "form" for a token in the page's form.
+- For a form payload, you MUST give body as name=value pairs joined with &, and content_type application/x-www-form-urlencoded. For JSON, you MUST give the JSON text and content_type application/json.
+- You MUST judge an API step on the server's answer: its status, or a value in the response. You MUST NOT judge it on what the page shows. You MUST NOT record an API answer with record_check. The api_request result is the evidence of an API step. To see the effect of the call in the UI, you SHOULD open or reload the page after it.
+- You MUST use every URL exactly as the task gives it. You MUST NOT add or remove a trailing slash, path segments, or parameters. When a URL that you changed fails, you MUST use the URL as given.

package/prompts/browser-capture.md

@@ -6,10 +6,10 @@ kind: fragment
 ---
 ## Acting so the run can become a test
 ForgeQE turns a passed run into an automated test. The test repeats your actions with real clicks and typing.
-- You MUST act only through the browser actions: click, input, select_dropdown, send_keys, and click_selector.
+- You MUST act only through the browser actions: click, input, select_dropdown, send_keys, and click_selector, and through api_request for a step that calls an API.
 - You MUST NOT click, submit, navigate, or change values from evaluate, for example with element.click(), dispatchEvent, `location.href = …`, or `.value`. A test cannot repeat these actions.
 - You MAY use evaluate only to read the page.
-- You MUST open a URL only for the start page, or when the task gives the URL.
+- You MUST open a URL only for the start page, or when the task gives the URL. Open it exactly as given: you MUST NOT add a trailing slash or change its path.
 - You MUST NOT add #section or ?parameters to a URL to go where a step takes you. That skips the step.
 - When you open a wrong URL, you MUST go back to the start page. Then do the steps.
 - When the control that you need has no index, you SHOULD find it with find_elements or evaluate. Then click it with click_selector and a CSS selector that matches only that element.

package/prompts/browser-checks.md

@@ -12,6 +12,8 @@ ForgeQE turns a passed run into an automated test. The test asserts the results
 - You MUST set `dynamic` to true for live data that changes on a different run, such as the date, a price, or a count. The test then asserts the rule, not this value.
 - You MUST record only the results that the task tells you to verify.
 - When the task lists expected results, you MUST record one check for each, and copy `expected` from that line.
+- When the task is a test case with numbered steps, you MUST set `step` to the number of the step that the result belongs to.
+- You MUST record the check of a step as soon as its expected result shows, before you start the next step.
 - ForgeQE finds the element that shows `text`. You MUST select text that points to the subject of the line:
   - For the items in a list, copy text from one item, such as the name of one result. Do not copy a summary line such as "2,463 properties found".
   - For a page or a section that opens, copy its heading or a different label that names it.

package/py/forgeqe_engine/api_step.py

@@ -0,0 +1,130 @@
+"""
+API steps in a browser run: api_request calls an HTTP endpoint from the page, in the browser's own session (its
+cookies go with the call), so a test case can mix API and UI steps on one logged-in user. Each call is recorded as an
+"api" step with its method, URL, body, and the response's status, so the verdict rests on the status the server
+gave, the replay and the written test repeat the call, and ForgeQE keeps it as a reusable API scenario.
+"""
+# No `from __future__ import annotations`: the library matches the injected browser_session parameter by its real type.
+import asyncio
+import json
+import logging
+from typing import Any, Dict
+
+from browser_use import ActionResult, BrowserSession
+
+logger = logging.getLogger("forgeqe_engine.api_step")
+
+# An endpoint that does not answer in this time fails the step instead of holding the run.
+CALL_TIMEOUT = 30.0
+
+API_SYSTEM_MESSAGE = """
+## API steps
+- For a step that calls an API (an HTTP method, an endpoint, or a payload), you MUST use api_request. You MUST NOT call fetch or XMLHttpRequest from evaluate.
+- Before the first api_request, you MUST open a page of the site. api_request runs in the browser's session and sends its cookies.
+- When the site needs a CSRF token, you MUST set csrf to "cookie" or "form". Use "cookie" for a csrftoken or XSRF-TOKEN cookie, and "form" for a token in the page's form.
+- For a form payload, you MUST give body as name=value pairs joined with &, and content_type application/x-www-form-urlencoded. For JSON, you MUST give the JSON text and content_type application/json.
+- You MUST judge an API step on the server's answer: its status, or a value in the response. You MUST NOT judge it on what the page shows. You MUST NOT record an API answer with record_check. The api_request result is the evidence of an API step. To see the effect of the call in the UI, you SHOULD open or reload the page after it.
+- You MUST use every URL exactly as the task gives it. You MUST NOT add or remove a trailing slash, path segments, or parameters. When a URL that you changed fails, you MUST use the URL as given.
+""".strip()
+
+# Runs in the page: the call carries the page's cookies; a CSRF token is read where the site keeps it.
+_FETCH_JS = r"""async (a) => {
+  const cookie = (n) => { const c = document.cookie.split('; ').find((x) => x.startsWith(n + '=')); return c ? decodeURIComponent(c.slice(n.length + 1)) : '' };
+  let token = '';
+  if (a.csrf === 'cookie') token = cookie('csrftoken') || cookie('XSRF-TOKEN') || cookie('csrf_token') || cookie('_csrf');
+  if (a.csrf === 'form') {
+    const f = document.querySelector('input[name="csrfmiddlewaretoken"], input[name="_csrf"], input[name="csrf_token"], input[name="authenticity_token"], input[name="__RequestVerificationToken"]');
+    const m = document.querySelector('meta[name="csrf-token"], meta[name="_csrf"]');
+    token = (f && f.value) || (m && m.content) || '';
+  }
+  const headers = {};
+  if (a.contentType) headers['Content-Type'] = a.contentType;
+  let body = a.body || undefined;
+  if (token) {
+    headers['X-CSRFToken'] = token;
+    headers['X-XSRF-TOKEN'] = token;
+    headers['X-CSRF-Token'] = token;
+    // A form post carries the token in the form too, as the site's own form would.
+    if (/x-www-form-urlencoded/i.test(a.contentType || '') && !/(^|&)(csrfmiddlewaretoken|_csrf|authenticity_token)=/.test(body || '')) body = (body ? body + '&' : '') + 'csrfmiddlewaretoken=' + encodeURIComponent(token);
+  }
+  const method = (a.method || 'GET').toUpperCase();
+  try {
+    const r = await fetch(a.url, { method, headers, body: method === 'GET' || method === 'HEAD' ? undefined : body, credentials: 'include', redirect: 'follow' });
+    const text = await r.text();
+    return { status: r.status, ok: r.ok, final_url: r.url, redirected: r.redirected, content_type: r.headers.get('content-type') || '', body: text.slice(0, 4000), csrf_sent: Boolean(token) };
+  } catch (e) {
+    return { error: String(e && e.message || e), page: location.href };
+  }
+}"""
+
+
+def _snippet(text: str, n: int = 300) -> str:
+    """The start of a response body on one line: JSON as it is, HTML without its tags."""
+    s = text.strip()
+    if s.startswith("<"):
+        import re
+
+        title = re.search(r"<title[^>]*>(.*?)</title>", s, re.I | re.S)
+        s = (f"[HTML: {title.group(1).strip()}] " if title else "[HTML] ") + re.sub(r"\s+", " ", re.sub(r"<[^>]+>", " ", s))
+    return " ".join(s.split())[:n]
+
+
+def describe(call: Dict[str, Any]) -> str:
+    """"POST https://shop.test/payment → 200, ended at https://shop.test/payment_done/1 · response: …" for the agent and the trace."""
+    if call.get("error"):
+        return f"{call['method']} {call['url']} failed: {call['error']}"
+    end = f", ended at {call['final_url']}" if call.get("redirected") and call.get("final_url") else ""
+    csrf = " (CSRF token sent)" if call.get("csrf_sent") else ""
+    return f"{call['method']} {call['url']}{csrf} → {call['status']}{end} · response: {call.get('snippet') or '(empty)'}"
+
+
+def register_api_request(tools: Any, captured: Dict[str, Any]) -> None:
+    """api_request: an HTTP call from the page's session; the call and its answer are captured for the step."""
+
+    @tools.action(
+        "Call an HTTP API endpoint from this browser's session (the session's cookies are sent) and get the status and "
+        "the start of the response. Use it for every step that calls an API; never fetch() from evaluate. "
+        "method: GET, POST, PUT, PATCH, or DELETE. url: exactly as the task gives it. body: name=value pairs joined with & "
+        "for a form, or JSON text. content_type: application/x-www-form-urlencoded or application/json. "
+        "csrf: empty, cookie, or form."
+    )
+    async def api_request(
+        method: str,
+        url: str,
+        browser_session: BrowserSession,
+        body: str = "",
+        content_type: str = "",
+        csrf: str = "",
+    ) -> ActionResult:
+        args = {"method": (method or "GET").upper(), "url": url, "body": body, "contentType": content_type, "csrf": (csrf or "").lower()}
+        try:
+            cdp = await browser_session.get_or_create_cdp_session()
+            res = await asyncio.wait_for(
+                cdp.cdp_client.send.Runtime.evaluate(
+                    params={"expression": f"({_FETCH_JS})({json.dumps(args)})", "awaitPromise": True, "returnByValue": True},
+                    session_id=cdp.session_id,
+                ),
+                timeout=CALL_TIMEOUT,
+            )
+            value = ((res or {}).get("result") or {}).get("value") or {}
+        except Exception as ex:  # The page went away, or the call could not be made.
+            value = {"error": str(ex)}
+        call: Dict[str, Any] = {"method": args["method"], "url": url, "body": body, "content_type": content_type, "csrf": args["csrf"]}
+        if value.get("error"):
+            call["error"] = value["error"]
+            captured["api"] = call
+            hint = " Open a page of this site first: the call is made from the page." if str(value.get("page", "")).startswith("about:") else ""
+            return ActionResult(error=f"api_request: {describe(call)}.{hint}")
+        call.update(
+            status=int(value.get("status") or 0),
+            ok=bool(value.get("ok")),
+            final_url=str(value.get("final_url") or url),
+            redirected=bool(value.get("redirected")),
+            content_type_received=str(value.get("content_type") or ""),
+            csrf_sent=bool(value.get("csrf_sent")),
+            snippet=_snippet(str(value.get("body") or "")),
+        )
+        captured["api"] = call
+        line = describe(call)
+        # A 4xx or 5xx is the server's answer, not a failed action: the agent judges it against what the step expects.
+        return ActionResult(extracted_content=line, long_term_memory=line)

package/py/forgeqe_engine/capture.py

@@ -12,6 +12,7 @@ Live capture for the test a passed run becomes, done while the page is still the
 import asyncio
 import json
 import logging
+import re
 import time
 from typing import Any, Dict, List, Optional
 
@@ -36,10 +37,10 @@ MAX_CLIMB = 5
 CAPTURE_SYSTEM_MESSAGE = """
 ## Acting so the run can become a test
 ForgeQE turns a passed run into an automated test. The test repeats your actions with real clicks and typing.
-- You MUST act only through the browser actions: click, input, select_dropdown, send_keys, and click_selector.
+- You MUST act only through the browser actions: click, input, select_dropdown, send_keys, and click_selector, and through api_request for a step that calls an API.
 - You MUST NOT click, submit, navigate, or change values from evaluate, for example with element.click(), dispatchEvent, `location.href = …`, or `.value`. A test cannot repeat these actions.
 - You MAY use evaluate only to read the page.
-- You MUST open a URL only for the start page, or when the task gives the URL.
+- You MUST open a URL only for the start page, or when the task gives the URL. Open it exactly as given: you MUST NOT add a trailing slash or change its path.
 - You MUST NOT add #section or ?parameters to a URL to go where a step takes you. That skips the step.
 - When you open a wrong URL, you MUST go back to the start page. Then do the steps.
 - When the control that you need has no index, you SHOULD find it with find_elements or evaluate. Then click it with click_selector and a CSS selector that matches only that element.
@@ -114,6 +115,45 @@ def action_name(action: Any) -> str:
     return next((k for k, v in data.items() if v is not None), "")
 
 
+_URL = re.compile(r"https?://[^\s\"'<>)\]]+")
+
+
+def task_urls(task: str) -> List[str]:
+    """The URLs the task gives, without the punctuation that ends a sentence around them."""
+    return [u.rstrip(".,;:!?") for u in _URL.findall(task or "")]
+
+
+def exact_task_url(url: str, given: Optional[List[str]]) -> Optional[str]:
+    """
+    The task's own URL when `url` differs from it only by a trailing slash. Models add one (/login/), and on many
+    sites that is a 404: the URL the task gave is the one to open. None when `url` is fine as it is.
+    """
+    if not url or not given or url in given:
+        return None
+    return next((t for t in given if t != url and t.rstrip("/") == url.rstrip("/")), None)
+
+
+def correct_task_urls(payload: Dict[str, Any], given: Optional[List[str]]) -> None:
+    """
+    A step's actions, as shown and recorded, with the task's own URL where the model added a slash: what install_effects
+    opens. The log, the trace, page memory, and the written test then all say the URL that was used.
+    """
+    actions = payload.get("actions") or []
+    for i, action in enumerate(actions):
+        for name in ("navigate", "api_request"):
+            params = action.get(name) if isinstance(action, dict) else None
+            if not isinstance(params, dict) or not params.get("url"):
+                continue
+            fixed = exact_task_url(str(params["url"]), given)
+            if not fixed:
+                continue
+            for key in ("action_lines", "plain_actions"):
+                lines = payload.get(key) or []
+                if i < len(lines) and isinstance(lines[i], str):
+                    lines[i] = lines[i].replace(str(params["url"]), fixed)
+            params["url"] = fixed
+
+
 def install_effects(tools: Any, effects: List[Dict[str, Any]], captured: Dict[str, Any]) -> None:
     """
     Wrap tools.act so each action call leaves {action, effect} in `effects`, in call order; click_selector also leaves
@@ -124,14 +164,25 @@ def install_effects(tools: Any, effects: List[Dict[str, Any]], captured: Dict[st
     async def act(action: Any, browser_session: Any = None, *args: Any, **kwargs: Any):
         session = browser_session if browser_session is not None else kwargs.get("browser_session")
         name = action_name(action)
+        # A URL the task gave, opened with a slash it does not have: open it exactly as given.
+        if name in ("navigate", "api_request"):
+            # The library's ActionModel is a root model: the action's parameters sit under .root.
+            params = getattr(getattr(action, "root", action), name, None)
+            fixed = exact_task_url(str(getattr(params, "url", "") or ""), captured.get("task_urls"))
+            if fixed and params is not None:
+                logger.info("%s: using the task's URL %s instead of %s", name, fixed, params.url)
+                params.url = fixed
         before = await page_state(session) if name in EFFECT_ACTIONS and session is not None else None
         captured.pop("target", None)
+        captured.pop("api", None)
         result = await original(action, browser_session, *args, **kwargs)
         entry: Dict[str, Any] = {"action": name, "effect": None}
         if name in EFFECT_ACTIONS and session is not None and not getattr(result, "error", None):
             entry["effect"] = await effect_after(session, before)
         if captured.get("target") is not None:
             entry["target"] = captured.pop("target")
+        if captured.get("api") is not None:
+            entry["api"] = captured.pop("api")
         effects.append(entry)
         return result
 

package/py/forgeqe_engine/checks.py

@@ -25,6 +25,8 @@ ForgeQE turns a passed run into an automated test. The test asserts the results
 - You MUST set `dynamic` to true for live data that changes on a different run, such as the date, a price, or a count. The test then asserts the rule, not this value.
 - You MUST record only the results that the task tells you to verify.
 - When the task lists expected results, you MUST record one check for each, and copy `expected` from that line.
+- When the task is a test case with numbered steps, you MUST set `step` to the number of the step that the result belongs to.
+- You MUST record the check of a step as soon as its expected result shows, before you start the next step.
 - ForgeQE finds the element that shows `text`. You MUST select text that points to the subject of the line:
   - For the items in a list, copy text from one item, such as the name of one result. Do not copy a summary line such as "2,463 properties found".
   - For a page or a section that opens, copy its heading or a different label that names it.
@@ -72,9 +74,10 @@ def register_checks(tools: Any, checks: List[Dict[str, Any]]) -> None:
         "Record one result the task asks you to verify, before done: expected (the result in a few words), "
         "text (the shortest exact text on the page that shows it, copied as shown), and dynamic=true when that text "
         "is live data that will differ on another run (today's date, a price, a count, today's featured item). "
-        "holds=false when the page does not show the expected result: then text is what the page shows instead."
+        "holds=false when the page does not show the expected result: then text is what the page shows instead. "
+        "step: when the task is a test case with numbered steps, the number of the step whose expected result this is."
     )
-    async def record_check(expected: str, text: str, browser_session: BrowserSession, dynamic: bool = False, holds: bool = True) -> ActionResult:
+    async def record_check(expected: str, text: str, browser_session: BrowserSession, dynamic: bool = False, holds: bool = True, step: int = 0) -> ActionResult:
         expected, text = " ".join(str(expected or "").split())[:200], " ".join(str(text or "").split())[:200]
         if not text:
             return ActionResult(error="Give the text on the page that shows the result.")
@@ -91,6 +94,9 @@ def register_checks(tools: Any, checks: List[Dict[str, Any]]) -> None:
         if not holds:
             # A failed expectation is a test result: `text` is what the page shows instead.
             check["holds"] = False
+        if isinstance(step, int) and step > 0:
+            # Which test step this checks: memory records where that step ended, to replay it after the case is edited.
+            check["step"] = step
         # The element showing the text and its section, with locators checked on this page, for the test's assertion.
         found = await locate_check(browser_session, text, dynamic=dynamic)
         if found: