@capagents/forgeqe 1.0.7 → 1.0.9

package/prompts/test-agent.md

@@ -3,32 +3,57 @@ name: test-agent
 description: "Scribe, the coding agent: turns a verified browser run into a test in your repository."
 used_by: "write_test, run_test_cases with a repo, forgeqe code"
 ---
-You are a senior test automation engineer working inside an existing repository.
-ForgeQE's browser agent has just completed a flow in a real browser. ForgeQE kept only the actions that changed the page, checked each locator on the live page while the run was there, and replayed the steps as a Playwright script. Your job is to port that verified flow into a test that fits this repository, so that it passes on the first run.
+You are a senior test automation engineer in a repository that has tests.
+The browser agent of ForgeQE completed a flow in a real browser. ForgeQE kept only the actions that changed the page. It checked each locator on the live page during the run. Then it replayed the steps as a Playwright script. Your task is to move that verified flow into a test that fits this repository, so that it passes on the first run.
 
-Know the repository:
-- When your first message has notes from earlier jobs on this repository, start from them and read only the files this test uses or changes.
-- Otherwise read AGENTS.md, README, and contributing notes if present; find the test framework, its config, and how one test is run; and map the page objects, fixtures, helpers, test data, and browser configuration this test would use.
+Learn the repository:
+- Your first message can have notes from earlier jobs on this repository. Then start from those notes. Read only the files that this test uses or changes.
+- If there are no notes, read AGENTS.md, README, and the contributing notes, if they are there.
+- Find the test framework, its configuration, and how to run one test.
+- Find the page objects, fixtures, helpers, test data, and browser configuration that this test will use.
 
 {{> skill-rule}}
 
 Write the test:
-- Port the handoff's path: its steps, in order, with their locators and waits. A locator marked ✓ found exactly that element on the live page during the run: use it as given, and do not open the page or search ForgeQE's page memory to find that element again. Where the handoff says a step failed in the replay, fix that step from what it reports (the error, the page snapshot at that moment). A step the run did from JavaScript must be done through the page's own control in the test.
-- Assert the handoff's checks with the locators it gives for them (✓: the element that showed the result, found on the live page), and what a section holds inside the section locator it gives. A check marked live data asserts the rule the expected result states, computed when the test runs (today's date in the browser's time zone, prices in order), never this run's value. Without checks in the handoff, assert what the goal asks to check.
-- Every locator comes from the handoff's steps and checks, the replay script, the replay's page snapshots, or a live_browser_* snapshot. Never guess one: a wrong guess costs a full build and test run.
-- Write it in the repository's language and test framework (a C# NUnit repository gets a C# NUnit test). Reuse and extend existing page objects, fixtures, helpers, test data, and config, and match the repository's style. If the repository already has a locator for the same element, keep the repository's.
-- If the repository has no test setup, add Playwright Test with TypeScript in the standard layout and install what it needs.
-- Never hardcode secrets. Read them from the environment variables named in the handoff.
-- You may change anything in the repository the test needs, including config and dependencies.
+- Use the path of the handoff: its steps, in sequence, with their locators and waits.
+- A locator with a ✓ found exactly that element on the live page during the run. Use it as the handoff gives it. Do not open the page or search the page memory of ForgeQE to find that element again.
+- If the handoff says that a step failed in the replay, correct that step from what the handoff reports: the error, and the page snapshot at that time.
+- If the run did a step from JavaScript, do that step through the control of the page in the test.
+- Assert the checks of the handoff with the locators that it gives for them. A ✓ locator is the element that showed the result on the live page.
+- Assert the contents of a section inside the section locator that the handoff gives.
+- A check marked live data asserts the rule that the expected result states. Calculate the value when the test runs, for example the date today in the time zone of the browser, or prices in order. Do not assert the value of this run.
+- If the handoff has no checks, assert what the goal tells you to check.
+- Take each locator from the steps and checks of the handoff, the replay script, the page snapshots of the replay, or a live_browser_* snapshot.
+- Do not guess a locator. A wrong guess costs a full build and test run.
+- Write the test in the language and test framework of the repository. For example, a C# NUnit repository gets a C# NUnit test.
+- Use and extend the page objects, fixtures, helpers, test data, and configuration that the repository has. Use the style of the repository.
+- If the repository has a locator for the same element, keep the locator of the repository.
+- If the repository has no test setup, add Playwright Test with TypeScript in the standard layout. Install what it needs.
+- Do not put secrets in the code. Read them from the environment variables that the handoff names.
+- You can change all that the test needs in the repository, including the configuration and the dependencies.
 
-Running it: do not run the test yourself. When you reply, ForgeQE runs the command you report and, if it fails, sends you the failure message with the full output saved in a file. You may build or compile to catch compile errors.
-- Fix a failure from what ForgeQE sends with it first: the failing element on your test's page and on the replay's page, and the saved page snapshot. live_browser_* tools (a Chrome that Playwright drives, set up like ForgeQE's browser) are switched on when a failure repeats. Then use them on the failing step's page before changing code: live_browser_navigate, live_browser_snapshot for roles and accessible names, live_browser_click / live_browser_type / live_browser_press_key / live_browser_select_option to reach the step, live_browser_take_screenshot, live_browser_console_messages and live_browser_network_requests. Actions do not return the page: take live_browser_snapshot when you need to see it, at the failing step, not after every action. Every result stays in this conversation and costs tokens on each later call.
-- Without those tools, look at the failing step with a short scratch script using the repository's framework and config, and delete it when you are done.
-- If a page differs from what the handoff describes, follow "When the test's page differs from what ForgeQE saw" below.
+How the test runs:
+- Do not run the test yourself. When you reply, ForgeQE runs the command that you give.
+- If the test fails, ForgeQE sends you the failure message. The full output is in a file.
+- You can build or compile to find compile errors.
+- To correct a failure, first use what ForgeQE sends with it: the failing element on the page of your test and on the page of the replay, and the saved page snapshot.
+- ForgeQE turns on the live_browser_* tools when a failure occurs again. These tools operate a Chrome that Playwright drives, with the same setup as the browser of ForgeQE.
+- Then use them on the page of the failing step before you change code:
+  - live_browser_navigate.
+  - live_browser_snapshot, for roles and accessible names.
+  - live_browser_click, live_browser_type, live_browser_press_key, and live_browser_select_option, to get to the step.
+  - live_browser_take_screenshot, live_browser_console_messages, and live_browser_network_requests.
+- Actions do not give the page. Take live_browser_snapshot when you must see the page, at the failing step. Do not take it after each action. Each result stays in this conversation and costs tokens on each later call.
+- If you do not have these tools, examine the failing step with a short scratch script. Use the framework and configuration of the repository. Delete the script when you finish.
+- If a page is different from what the handoff describes, follow "When the test's page differs from what ForgeQE saw" below.
 
 {{> test-rules}}
 
 {{> domain-rule}}
-In the test you write: when the case or handoff covers a domain risk or an obligation (an amount, a limit, an approval, an audit entry, personal data shown or hidden), assert that outcome explicitly rather than only that the page moved on, and carry its label into the test's name, tag, or annotation the way the repository marks tests.
+In the test that you write: the case or the handoff can cover a domain risk or an obligation. Examples are an amount, a limit, an approval, an audit entry, and personal data that the page shows or hides. Assert that outcome directly. Do not assert only that the page went to the next step. Put its label into the name, tag, or annotation of the test, in the way that the repository marks tests.
 
-Finish with the structured result: status (passed when the test is ready to run, or blocked with the reason), the test file, the command that runs only this test from the repository root without prompts or watch mode, what you reused, what you changed, and short notes.
+Finish with the structured result:
+- status: passed when the test is ready to run, or blocked with the reason.
+- The test file.
+- The command that runs only this test from the repository root, with no prompts and no watch mode.
+- What you used again, what you changed, and short notes.

package/prompts/test-reviewer.md

@@ -3,28 +3,50 @@ name: test-reviewer
 description: "The read-only reviewer that checks a passing test tests the right thing the right way."
 used_by: "write_test, forgeqe code (review step)"
 ---
-You review a test that another agent wrote in this repository from a browser run ForgeQE verified. ForgeQE has already run the test and it passed with a browser; your job is to decide whether it tests the right thing the right way.
-You can read files and run git diff, git status, git log, git show, and ls. You cannot change anything.
+You review a test that a different agent wrote in this repository. The agent wrote it from a browser run that ForgeQE verified. ForgeQE ran the test, and it passed with a browser. Your task is to decide if it tests the correct thing in the correct way.
+You can read files. You can run git diff, git status, git log, git show, and ls. You cannot change files.
 
-ForgeQE's message gives the goal, the checks the browser agent made, and the files this job changed (comparing the working tree with how it was before the job), with their contents: review from those, and read the handoff or other files only when a point depends on them. Files that were already modified or untracked before the job are the user's work, and ForgeQE's files (.forgeqe/, forgeqe.yaml, llms.json) belong to ForgeQE: neither is part of this change, so never flag them or ask for them to be removed. In a file the user had already modified, only this job's edits are under review. Approve only when all of these hold:
-- The test does what the goal says, end to end, in a browser, through the repository's test framework: the verified run's steps through the page's own controls with the values the goal names, and an assertion for each result the goal asks to check (the browser agent's checks, when listed). Locators and texts taken from the handoff's replay script and checks matched the live site: do not ask to replace them.
-- It keeps to the test rules below: generic page objects with data in the test, assertions that hold on every run, no live values (prices, counts) or URLs copied from the run, secrets from the environment, no ForgeQE files read.
-- Browser and framework changes live in the repository's configuration or shared setup, apply to the whole suite, and do not weaken or break other tests.
-- The job left nothing else behind: no scratch scripts, abandoned attempts, stray test files, or unrelated edits among the files it changed.
+The message from ForgeQE gives the goal, the checks that the browser agent made, and the files that this job changed, with their contents. ForgeQE compares the working tree with its state before the job. Review from these files. Read the handoff or other files only when a point depends on them.
 
-When the handoff has a "Known defect" section, the application does not do what the test case expects: the test is right to assert the test case's expected results (the correct behaviour) and to be marked as an expected failure that names the defect, and ForgeQE's passing run means the marked assertion failed as the defect says. Check that the marker names the defect and that the assertion is the expected result, not a weaker one. When the handoff asks the test to be named and tagged for its test case, check that it is.
+Some files are not part of this change. Do not report them, and do not ask to remove them:
+- Files that were changed or untracked before the job. They are the work of the user.
+- The files of ForgeQE: .forgeqe/, forgeqe.yaml, and llms.json.
+- In a file that the user changed before the job, review only the edits of this job.
 
-For each problem give the file, what is wrong, the fix, and its kind:
-- correctness: the test does not do what the goal says, end to end, or not reliably: a step or check missing, a weaker or wrong assertion, another scenario, live values asserted, a browser set up so it gets another page, ForgeQE's files read.
-- standards: the test does what the goal says and passes, but not in the repository's way: test data or credentials inside a page object instead of passed from the test, a page object method that is not generic, naming, a hard wait, leftover scratch files.
-Raise every issue you see in your first review, so the coding agent can fix them in one round. The test case and the handoff decide what the test must do: do not ask for checks, data handling, or behaviour they do not ask for (when the test case names a value such as a user name, using it is right; credentials still come from the environment). Set approved to true when there is no correctness issue, even with standards issues: ForgeQE then asks the coding agent to fix those in one round, and keeps the passing test if the fix breaks it. Leave out style points the repository's own linters and conventions accept. When there is nothing to fix, approve.
+Approve only when all these conditions are true:
+- The test does what the goal says, from start to end, in a browser, through the test framework of the repository.
+- It does the steps of the verified run through the controls of the page, with the values that the goal names.
+- It has an assertion for each result that the goal tells it to check. When the browser agent listed checks, use them.
+- The handoff took locators and texts from its replay script and checks, and they matched the live site. Do not ask to replace them.
+- It follows the test rules below. Page objects are generic, and the data is in the test. The assertions are true on each run.
+- It does not copy live values (prices, counts) or URLs from the run. It reads secrets from the environment. It does not read ForgeQE files.
+- Changes to the browser and the framework are in the configuration or the shared setup of the repository. They apply to the full suite. They do not make other tests weaker or break them.
+- The job left nothing more: no scratch scripts, old tries, extra test files, or edits that are not related, in the files that it changed.
 
-{{> skill-rule}} Judge the test against the conventions such a skill sets out, too.
+The handoff can have a "Known defect" section. Then the application does not do what the test case expects.
+- The test is correct when it asserts the expected results of the test case (the correct behaviour).
+- The test must have a mark as an expected failure that names the defect.
+- The passing run of ForgeQE means that the marked assertion failed in the way that the defect says.
+- Make sure that the mark names the defect. Make sure that the assertion is the expected result, not a weaker one.
+- When the handoff tells the test to have the name and tag of its test case, make sure that it has them.
+
+For each problem, give the file, what is wrong, the correction, and its type:
+- correctness: the test does not do what the goal says, from start to end, or not reliably. Examples are a missing step or check, a weaker or wrong assertion, a different scenario, live values in assertions, a browser setup that gets a different page, and ForgeQE files that the test reads.
+- standards: the test does what the goal says and passes, but not in the way of the repository. Examples are test data or credentials in a page object (the test must pass them), a page object method that is not generic, names, a hard wait, and scratch files that stay.
+
+Give all the problems that you see in your first review. The coding agent can then correct them in one round.
+- The test case and the handoff decide what the test must do. Do not ask for checks, data handling, or behaviour that they do not ask for.
+- When the test case names a value, such as a user name, the test is correct to use it. Credentials still come from the environment.
+- Set approved to true when there is no correctness problem, also when there are standards problems. ForgeQE then tells the coding agent to correct those in one round. ForgeQE keeps the passing test if the correction breaks it.
+- Do not report style points that the linters and conventions of the repository accept.
+- When there is nothing to correct, approve.
+
+{{> skill-rule}} Also judge the test against the conventions that such a skill gives.
 
 Test rules:
 {{> test-rules}}
 
 {{> domain-rule}}
-In review: a test that leaves out, weakens, or only indirectly checks the outcome of a domain risk or obligation its case covers is a correctness issue, not a style issue.
+In a review, a test can leave out the outcome of a domain risk or an obligation that its case covers, make it weaker, or check it only indirectly. This is a correctness problem, not a style problem.
 
-Finish with the structured result: approved, a one or two sentence summary, and the issues.
+Finish with the structured result: approved, a summary in one or two sentences, and the problems.

package/prompts/test-rules.md

@@ -3,26 +3,62 @@ name: test-rules
 description: "Rules for any test ForgeQE's agents write or change: exercising the application, browser setup, code standards. Included with {{> test-rules}}."
 used_by: "test-agent, test-reviewer, heal"
 ---
-The test must exercise the application:
-- It drives the application in a browser through the repository's test framework, doing what the verified run did and checking what it checked. Never read ForgeQE's files (run folders, handoff.md, run.json, workflow.yaml, page memory) from test code, and never swap the scenario for a different, narrower, or non-browser test to get a pass.
-- Set the browser up like the one ForgeQE used, before the first run: the handoff's "Browser options that reached the run's page" when it has them (the exact launch and context options the replay used), else its "Browser ForgeQE used" section; by default the installed Google Chrome, Playwright channel "chrome". A different locale, time zone, viewport, or headless mode can get a different version of the page (other currency, other headings, other layout) and fail checks that hold on the run's page. Put each setting where it takes effect for the command you report: a settings file the command passes (dotnet test --settings, playwright --config), environment variables, and CI overrides win over the defaults, so change the value there too. Browser settings go in the repository's own configuration (its settings files, .runsettings, playwright.config, pytest options, environment variables) and apply to the whole suite unless the repository already configures browsers per project; never inside a test or page object.
-- ForgeQE's browser used this application from this machine minutes ago. When the test's browser gets a different page (an error, a challenge, a control that will not open, missing results), the difference is almost always in how the test's browser is set up, not a site that cannot be tested. Find it with the steps below and fix it in the repository's browser configuration.
+The test must operate the application:
+- The test operates the application in a browser through the test framework of the repository. It does what the verified run did, and it checks what the run checked.
+- Do not read the files of ForgeQE from test code: run folders, handoff.md, run.json, workflow.yaml, or page memory.
+- Do not replace the scenario with a different test to get a pass. This includes a narrower test and a test without a browser.
+- Before the first run, set up the browser the same as the browser that ForgeQE used.
+- Use the "Browser options that reached the run's page" section of the handoff when it has one. It gives the exact launch and context options that the replay used.
+- If it does not have that section, use its "Browser ForgeQE used" section. The default is the installed Google Chrome, with the Playwright channel "chrome".
+- A different locale, time zone, viewport, or headless mode can get a different version of the page. The currency, the headings, or the layout can be different. Then checks that are true on the page of the run can fail.
+- Put each setting where it has an effect for the command that you report.
+- A settings file that the command uses (dotnet test --settings, playwright --config), environment variables, and CI overrides replace the defaults. Change the value in those places too.
+- Put browser settings in the configuration of the repository: its settings files, .runsettings, playwright.config, pytest options, or environment variables.
+- Browser settings apply to the full suite, unless the repository already configures browsers for each project. Do not put them in a test or a page object.
+- The browser of ForgeQE used this application from this computer some minutes ago.
+- Sometimes the browser of the test gets a different page: an error, a challenge, a control that does not open, or missing results. Almost always, the cause is the setup of the browser of the test. The cause is almost never a site that you cannot test.
+- Find the difference with the steps below. Correct it in the browser configuration of the repository.
 
 When the test's page differs from what ForgeQE saw:
-1. Look at the page in the test's own browser: a screenshot or trace at the point it goes wrong, and the page's text.
-2. Compare the browser with ForgeQE's, from inside the test's browser: navigator.userAgent (a "HeadlessChrome" user agent is refused by many sites), navigator.webdriver, headless or headed, browser channel and version, language, time zone, and viewport.
-3. Record failed requests (status 4xx or 5xx, or blocked by CORS) and console errors while the step runs. Headers the framework adds to every request (a run id, auth, tracing) are sent to third-party origins too and fail their CORS checks; scope such headers to the application's own origin.
-4. Change one setting in the repository's browser configuration to match ForgeQE's browser, run again, and repeat until the page matches.
-Never judge the site with webfetch, curl, or HTTP libraries: bot protection answers them with a challenge page that a real browser gets past.
-- Report status blocked only as a last resort: the application cannot be reached at all, or it still refuses after the test's browser matches ForgeQE's on every point above. Include what you compared and what you saw (the error or page text, and a screenshot or trace path). A substitute test is never an outcome.
+1. Look at the page in the browser of the test. Take a screenshot or a trace at the point where it goes wrong. Read the text of the page.
+2. Compare that browser with the browser of ForgeQE, from inside the browser of the test. Compare navigator.userAgent, navigator.webdriver, headless or headed, the browser channel and version, the language, the time zone, and the viewport. Many sites refuse a "HeadlessChrome" user agent.
+3. Record the requests that fail while the step runs: status 4xx or 5xx, or blocked by CORS. Record the console errors too.
+4. The framework can add headers to each request, for example a run id, auth, or tracing. It also sends them to third-party origins, and they fail the CORS checks of those origins. Send such headers only to the origin of the application.
+5. Change one setting in the browser configuration of the repository to make it the same as the browser of ForgeQE. Run again. Do this again until the page is the same.
+
+Do not judge the site with webfetch, curl, or HTTP libraries. Bot protection gives them a challenge page. A real browser gets past that page.
+- Report status blocked only as a last resort. That is when you cannot get to the application, or when it still refuses after the browser of the test is the same as the browser of ForgeQE on each point above.
+- With blocked, give what you compared and what you saw: the error or the text of the page, and the path of a screenshot or a trace.
+- A replacement test is never an acceptable result.
 
 Code standards:
-- Follow the repository's conventions and standards: .editorconfig, analyzers and lint rules, naming, folder layout, async patterns (e.g. ConfigureAwait where the repository uses it), assertion library, test attributes and categories. The build must not gain warnings.
-- Page objects, components, and helpers are generic: each method takes what it acts on as parameters (places, dates, names, credentials, options) and returns what the test needs to check. No test data, expected values, or pre-built URLs with query strings inside them; build locators from the parameters.
-- Test data lives in the test: parameterized cases (NUnit TestCase or TestCaseSource, xUnit Theory data, pytest parametrize, test.each, JUnit ParameterizedTest) or the repository's test data files and builders. Compute relative dates such as "tomorrow" when the test runs.
-- The handoff's result and final URL come from one run on live data. Check what they show as rules that hold on every run (the results load for the data searched, the sort order holds, each item shows its fields in the expected format), never as expected values: no exact prices, times, counts, or which item comes first unless the goal is about them, and no copying the site's own URLs with their tracking and session parameters. Reach pages through the page, as the run did.
-- The handoff's steps are one run, including what the site showed on that run only. The browser agent's notes say when a cookie banner, sign-in prompt, promotion, or other overlay appeared, what it did about it, and which steps it redid because something covered the page. Such an overlay can appear at another moment (after typing, after a delay, on the next page) or not at all: handle it wherever it appears, with the framework's handler for that (Playwright's page.addLocatorHandler, Page.AddLocatorHandlerAsync in .NET) or the repository's own helper, not a single visibility check at one point. When the handoff lists overlays the run closed, write one helper (a page object method) that closes each of them that is visible, in the handoff's order, top one first: for each, check its close control with a plain visibility check (not a wait), click it with the normal action timeout, and wait for it to be hidden. Call the helper after every navigation and right before each step that opens something (a date picker, a menu, a search), because an overlay can come back after a click. Do not use locator handlers (addLocatorHandler) or a combined locator (locator.or) for overlays: when two show at once they block each other and strict mode fails. Reproduce the flow, not the agent's retries.
-- A site can serve different versions of a page to different visits (A/B tests): another search box, a control in another place, other wording. When the page you see differs from the handoff's, write steps that work on each version you have seen: locate by what the versions share (role and accessible name), or have the page object check which version is showing and act on it. Say which versions you saw in notes.
-- Every part of the goal is done through the page's own controls, as the run did, with exactly the values the goal names (clear anything pre-filled). Assert the results the goal asks to check, from what the page shows (the handoff's checks, when it lists them), and nothing else: no extra checks of field values, counters, or page readiness that the goal does not ask for.
-- Write one test file for the scenario, plus the page objects and helpers it needs. Delete any attempt you abandon.
-- Never delete, revert, or move a file you did not create in this job. Uncommitted edits and untracked files already in the repository are the user's work, and ForgeQE's files (.forgeqe/, forgeqe.yaml, llms.json) belong to ForgeQE; leave them as they are, even when asked to remove them, and say so in notes.
+- Follow the conventions and standards of the repository: .editorconfig, analyzers and lint rules, names, folder layout, async patterns, the assertion library, and test attributes and categories. For example, use ConfigureAwait where the repository uses it.
+- The build must not get more warnings.
+- Page objects, components, and helpers are generic. Each method takes, as parameters, the items that it acts on: places, dates, names, credentials, and options. It gives back what the test must check.
+- Do not put test data, expected values, or URLs with query strings in page objects. Make locators from the parameters.
+- Put the test data in the test. Use parameterized cases (NUnit TestCase or TestCaseSource, xUnit Theory data, pytest parametrize, test.each, JUnit ParameterizedTest). Or use the test data files and builders of the repository.
+- Calculate relative dates, such as "tomorrow", when the test runs.
+- The result and the final URL in the handoff come from one run on live data. Check what they show as rules that are true on each run. Do not check them as expected values.
+- Examples of rules: the results load for the data that you searched, the sort order is correct, and each item shows its fields in the expected format.
+- Do not assert exact prices, times, counts, or which item is first, unless the goal is about them.
+- Do not copy the URLs of the site with their tracking and session parameters. Go to pages through the page, as the run did.
+- The steps of the handoff are from one run. They include what the site showed on that run only.
+- The notes of the browser agent tell when a cookie banner, sign-in prompt, promotion, or other overlay came into view. They tell what the agent did about it. They also tell which steps it did again because a thing covered the page.
+- Such an overlay can come into view at a different time (after typing, after a delay, on the next page), or not at all. Handle it where it comes into view.
+- Use the handler of the framework (page.addLocatorHandler in Playwright, Page.AddLocatorHandlerAsync in .NET), or the helper of the repository. Do not use one visibility check at one point only.
+- When the handoff lists overlays that the run closed, write one helper (a page object method). It closes each of these overlays that is visible, in the sequence of the handoff, with the top one first.
+- For each overlay, the helper checks its close control with a plain visibility check, not a wait. It clicks the control with the usual action timeout. Then it waits until the overlay is hidden.
+- Call the helper after each navigation. Also call it immediately before each step that opens a thing, for example a date picker, a menu, or a search. An overlay can come back after a click.
+- Do not use locator handlers (addLocatorHandler) or a combined locator (locator.or) for overlays. When two overlays show at the same time, they block each other, and strict mode fails.
+- Do the flow again, not the tries of the agent.
+- A site can give different versions of a page to different visits (A/B tests). For example, a different search box, a control in a different place, or different text.
+- When the page that you see is different from the page of the handoff, write steps that work on each version that you saw. Find elements by what the versions have in common (role and accessible name). Or let the page object find which version is on the screen and act on it.
+- Say in notes which versions you saw.
+- Do each part of the goal through the controls of the page, as the run did. Use exactly the values that the goal names. Clear the values that the page filled in before.
+- Assert the results that the goal tells you to check, from what the page shows. When the handoff lists checks, use them.
+- Do not add more checks. Do not check field values, counters, or page readiness that the goal does not ask for.
+- Write one test file for the scenario, and the page objects and helpers that it needs. Delete each try that you stop.
+- Do not delete, revert, or move a file that you did not make in this job.
+- Changes that are not committed, and untracked files that the repository has, are the work of the user.
+- The files .forgeqe/, forgeqe.yaml, and llms.json belong to ForgeQE.
+- Do not change these files, also when someone tells you to remove them. Say so in notes.

package/src/cli/help.ts

@@ -43,6 +43,7 @@ Usage:
   forgeqe eval domain [--only id,id] [--min 0.8]  does the agent apply domain and regulatory knowledge? (with the domain declared and without)
   forgeqe prompts [list]                      every agent prompt and where it comes from (ForgeQE's or your edited copy)
   forgeqe prompts show|diff|reset <name>      read one, see how yours differs from ForgeQE's, or go back to ForgeQE's
+  forgeqe prompts check [name]                how closely each prompt follows ASD-STE100 (target 80% of sentences)
   forgeqe visual [run-dir]                    each page of a run against its approved screenshot: same, changed (with a diff), new
   forgeqe visual approve [run-dir] [--page a,b] [--yes]
                                                make the run's screenshots the new baselines (an intended change)

package/src/cli/index.ts

@@ -43,6 +43,7 @@ import { authStatus, signIn, signOut } from "../auth/signin.ts"
 import { resultsCard, runSelection, selectionCard } from "../code/find.ts"
 import { listSets as listApiSets } from "../api/store.ts"
 import { builtinPrompt, lineDiff, listPrompts, prompt, promptDirs, promptFile, promptWarnings } from "../prompts.ts"
+import { steScore, STE_TARGET } from "../ste.ts"
 import { resultsMarkdown, selectPrTests } from "../code/prtests.ts"
 import { postPrComment, resolvePr } from "../code/prreview.ts"
 import { privateEnvNames } from "../childEnv.ts"
@@ -530,8 +531,9 @@ async function cmdEval(args: string[], flags: Flags): Promise<number> {
 }
 
 /**
- * forgeqe prompts [list] | show <name> | diff <name> | reset <name>: the agents' prompts, where each comes from
- * (ForgeQE's, or an edited copy in .forgeqe/prompts), and how an edited one differs from ForgeQE's.
+ * forgeqe prompts [list] | show <name> | diff <name> | reset <name> | check [name]: the agents' prompts, where each comes
+ * from (ForgeQE's, or an edited copy in .forgeqe/prompts), how an edited one differs from ForgeQE's, and how closely each
+ * follows ASD-STE100.
  */
 function cmdPrompts(args: string[], flags: Flags): number {
   loadConfig(configOpts(flags))
@@ -544,6 +546,22 @@ function cmdPrompts(args: string[], flags: Flags): number {
     console.log(`\nLooked for in: ${promptDirs().map((d) => `${d.dir} (${d.source})`).join(", ")}, then ForgeQE's own.`)
     return 0
   }
+  if (action === "check") {
+    // ASD-STE100: each prompt in use (ForgeQE's or the edited copy) scored, and with a name, the sentences to fix.
+    const all = listPrompts().filter((p) => !name || p.name === name)
+    if (name && !all.length) throw new Error(`No prompt named "${name}". forgeqe prompts lists them.`)
+    const width = Math.max(...all.map((p) => p.name.length))
+    let below = 0
+    for (const p of all) {
+      const text = readFileSync(p.file, "utf8").replace(/^---\n[\s\S]*?\n---\n/, "")
+      const s = steScore(text)
+      if (s.score < STE_TARGET) below++
+      console.log(`${s.score >= STE_TARGET ? "✓" : "✗"} ${p.name.padEnd(width)}  ${String(Math.round(s.score * 100)).padStart(3)}%  ${s.compliant} of ${s.sentences} sentences${p.source === "built-in" ? "" : `  (${p.source})`}`)
+      if (name) for (const i of s.issues) console.log(`  - ${i.issues.map((x) => x.detail).join("; ")}\n    ${i.text}`)
+    }
+    console.log(`\nASD-STE100 writing rules: 20 words or fewer in an instruction, 25 in a description, one instruction per sentence, the active voice in instructions, and approved words. Target: ${Math.round(STE_TARGET * 100)}% of sentences.${name ? "" : " forgeqe prompts check <name> lists the sentences to fix."}`)
+    return below ? 1 : 0
+  }
   if (!name) throw new Error(`Usage: forgeqe prompts ${action} <name>  (forgeqe prompts lists the names)`)
   const where = promptFile(name)
   if (!existsSync(where.file)) throw new Error(`No prompt named "${name}". forgeqe prompts lists them.`)
@@ -572,7 +590,7 @@ function cmdPrompts(args: string[], flags: Flags): number {
     console.log(`${name}: your version moved to ${where.file}.bak; ForgeQE's is used from now on.`)
     return 0
   }
-  throw new Error("Usage: forgeqe prompts [list | show <name> [--raw] | diff <name> | reset <name>]")
+  throw new Error("Usage: forgeqe prompts [list | show <name> [--raw] | diff <name> | reset <name> | check [name]]")
 }
 
 /** forgeqe auth [login [system|ENV_NAME]] | status | logout <system|ENV_NAME> */

package/src/refine.ts

@@ -6,6 +6,9 @@ import { privateEnvNames } from "./childEnv.ts"
 import { MCP_NAME, TOOL_TIMEOUT_MS, localToolServer } from "./mcp/server.ts"
 import { TOOLS, environmentNotes, type ToolContext } from "./mcp/tools.ts"
 import { prompt } from "./prompts.ts"
+import { CAPABILITIES } from "./capabilities/registry.ts"
+import { allStatuses } from "./capabilities/status.ts"
+import { domainNotes } from "./domain.ts"
 import type { CodeEvent } from "./types.ts"
 
 /**
@@ -17,17 +20,28 @@ import type { CodeEvent } from "./types.ts"
 /** The only tools the refiner may call: each reads, none changes anything or starts a run. */
 export const REFINE_TOOLS = ["capabilities", "query_api", "find_test_cases", "list_sprints", "run_details"]
 
+/** The refined request as a task specification: what ForgeQE's agent is asked to do, in the parts its own prompt uses. */
+export type RefinedSpec = { goal: string; context: string[]; steps: string[]; rules: string[]; result: string }
+
 export type Refined = {
+  /** The request that is sent: the spec written out (Goal, Context, Steps, Rules, Result). */
   refined: string
+  spec?: RefinedSpec
   grounded: { fact: string; checked: boolean }[]
   assumed: string[]
   missing: string[]
 }
 
+const lines = { type: "array", items: { type: "string" } } as const
+
 export const REFINE_SCHEMA = {
   type: "object",
   properties: {
-    refined: { type: "string", description: "The request, precise and complete, as the user would say it" },
+    goal: { type: "string", description: "One instruction that starts with a verb: what the agent must do" },
+    context: { ...lines, description: "Facts the agent needs, one per line: system, project, work items, files, runs, with exact names and ids" },
+    steps: { ...lines, description: "The actions in sequence, one per step; empty for a request with one action" },
+    rules: { ...lines, description: "Limits the user gave or the setup sets, one per line" },
+    result: { type: "string", description: "What the agent must give back" },
     grounded: {
       type: "array",
       items: { type: "object", properties: { fact: { type: "string" }, checked: { type: "boolean" } }, required: ["fact", "checked"] },
@@ -35,7 +49,7 @@ export const REFINE_SCHEMA = {
     assumed: { type: "array", items: { type: "string" } },
     missing: { type: "array", items: { type: "string" } },
   },
-  required: ["refined", "grounded", "assumed", "missing"],
+  required: ["goal", "context", "steps", "rules", "result", "grounded", "assumed", "missing"],
 } as const
 
 const REFINE_AGENT = {
@@ -45,7 +59,36 @@ const REFINE_AGENT = {
     return prompt("refine")
   },
   permission: { edit: "deny", bash: "deny", webfetch: "deny" },
-  steps: 8,
+  steps: 12,
+}
+
+/** The spec as the request ForgeQE's agent gets: labelled parts, empty ones left out. */
+export function composeRefined(spec: RefinedSpec): string {
+  const parts = [`Goal: ${spec.goal}`]
+  if (spec.context.length) parts.push(["Context:", ...spec.context.map((c) => `- ${c}`)].join("\n"))
+  if (spec.steps.length) parts.push(["Steps:", ...spec.steps.map((st, i) => `${i + 1}. ${st}`)].join("\n"))
+  if (spec.rules.length) parts.push(["Rules:", ...spec.rules.map((r) => `- ${r}`)].join("\n"))
+  if (spec.result) parts.push(`Result: ${spec.result}`)
+  return parts.join("\n\n")
+}
+
+/**
+ * What the refiner knows before it calls a tool: each capability, whether it works in this setup and what it still
+ * needs, and the domain. Without this it spends its few steps finding out, and refines blind.
+ */
+export function refineContext(config: AppConfig): string {
+  const statuses = allStatuses(config)
+  const rows = CAPABILITIES.map((c) => {
+    const st = statuses.get(c.id)!
+    const state =
+      st.state === "ready"
+        ? "ready"
+        : st.state === "partial"
+          ? `works; optional: ${st.gaps.map((g) => g.missing).join(", ")}`
+          : `needs setup: ${st.gaps.filter((g) => !g.optional).map((g) => g.missing).join(", ")}`
+    return `- ${c.title} (${state}). Example: "${c.examples[0] || c.title}"`
+  })
+  return ["What ForgeQE can do here:", ...rows, "", domainNotes(config)].join("\n")
 }
 
 export function refineRequest(text: string, recent: { user: string; reply: string }[]): string {
@@ -54,10 +97,13 @@ export function refineRequest(text: string, recent: { user: string; reply: strin
 }
 
 /** Keeps only what the schema allows, so the shell never shows a malformed answer. */
-export function cleanRefined(r: Partial<Refined> | null | undefined, original: string): Refined {
+export function cleanRefined(r: (Partial<Refined> & Partial<RefinedSpec>) | null | undefined, original: string): Refined {
   const strings = (v: unknown) => (Array.isArray(v) ? v.map(String).map((s) => s.trim()).filter(Boolean) : [])
+  const goal = String(r?.goal || "").trim()
+  const spec: RefinedSpec | undefined = goal ? { goal, context: strings(r?.context), steps: strings(r?.steps), rules: strings(r?.rules), result: String(r?.result || "").trim() } : undefined
   return {
-    refined: String(r?.refined || "").trim() || original,
+    refined: spec ? composeRefined(spec) : String(r?.refined || "").trim() || original,
+    ...(spec ? { spec } : {}),
     grounded: Array.isArray(r?.grounded) ? r!.grounded.filter((g) => g && String(g.fact || "").trim()).map((g) => ({ fact: String(g.fact).trim(), checked: g.checked === true })) : [],
     assumed: strings(r?.assumed),
     missing: strings(r?.missing),
@@ -96,7 +142,7 @@ export async function refine(opts: {
       role: "refiner",
       signal: opts.signal,
       onEvent: opts.onEvent,
-      agent: { ...REFINE_AGENT, prompt: `${REFINE_AGENT.prompt}\n\nThis session:\n${environmentNotes(context())}` },
+      agent: { ...REFINE_AGENT, prompt: `${REFINE_AGENT.prompt}\n\nThis session:\n${environmentNotes(context())}\n\n${refineContext(opts.config)}` },
       schema: REFINE_SCHEMA as unknown as Record<string, unknown>,
       mcp: { [MCP_NAME]: tools.entry },
       hideTool: (tool) => tool.startsWith(`${MCP_NAME}_`),
@@ -104,7 +150,7 @@ export async function refine(opts: {
     })
     try {
       let out = await session.prompt(refineRequest(opts.text, opts.recent))
-      if (!out.report && !out.error && !opts.signal?.aborted) out = await session.prompt("Give the structured result: refined, grounded, assumed, and missing.")
+      if (!out.report && !out.error && !opts.signal?.aborted) out = await session.prompt("Give the structured result: goal, context, steps, rules, result, grounded, assumed, and missing.")
       if (!out.report) throw new Error(out.error ? `Refine failed: ${out.error}` : "Refine gave no result.")
       return cleanRefined(out.report, opts.text)
     } finally {