blastproof 0.11.0 → 0.12.1

package/README.md

@@ -1,4 +1,10 @@
-# blastproof
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./.github/logo-dark.svg">
+    <img src="./.github/logo-light.svg" alt="" width="30" height="30">
+  </picture>
+  blastproof
+</h1>
 
 [![CI](https://github.com/hamc/blastproof/actions/workflows/ci.yml/badge.svg)](https://github.com/hamc/blastproof/actions/workflows/ci.yml)
 [![Dogfood](https://github.com/hamc/blastproof/actions/workflows/dogfood.yml/badge.svg)](https://github.com/hamc/blastproof/actions/workflows/dogfood.yml)
@@ -12,6 +18,10 @@ git diff → impact mapping → test generation → agentic execution → report
 
 100% local. MIT. Bring your own LLM key.
 
+▶ **[Watch the introduction](https://www.youtube.com/shorts/miqN5FzMF_k)** — what it does, in a minute.
+
+**Documentation:** [Configuration](./docs/configuration.md) · [Testing behind a login](./docs/auth.md) · [Running in CI](./docs/ci.md) · [Contributing](./CONTRIBUTING.md) · [Architecture](./AGENTS.md)
+
 ## Quick start
 
 ```bash
@@ -38,21 +48,53 @@ blastproof run
 
 Before `run`, `plan` or `test` do anything, they check what they are about to spend — the browser can launch, the model provider is reachable, `base_url` responds — and report every unmet one together, so a stopped app or a missing browser is never a wall you hit one crash at a time. A missing system library names the exact install command and says it needs root; nothing is installed on your behalf. Silent when everything is fine, and skipped entirely by `--dry-run`, which needs none of it.
 
+Provider options, budgets and browser tuning: [Configuration](./docs/configuration.md).
+
 ## Does this fit your application?
 
-**Your markup must be accessible — a hard requirement.** Elements are found by role, label or visible text from the accessibility tree. That is what removes selectors and survives redesigns; the cost is that an interface the accessibility tree cannot describe cannot be driven at all, and there is deliberately no CSS or XPath fallback. Icon-only buttons without accessible names, `div`-based controls and ARIA-less dropdowns simply cannot be targeted. Run an accessibility checker first — the result predicts how well this will work better than anything else.
+Three questions. The first one decides most cases.
+
+### 1. Is your markup accessible?
+
+**A hard requirement, not a preference.** blastproof finds elements the way a screen reader does — by role, by label, by visible text. That is what removes selectors and survives redesigns. The cost is that there is deliberately no CSS or XPath fallback, so anything the accessibility tree cannot describe cannot be driven at all.
+
+| works | cannot be driven |
+| --- | --- |
+| `<button>Add to cart</button>` | a `<div>` with a click handler |
+| `<label for="email">` + `<input>` | an input with no label |
+| `<button aria-label="Delete note">` | an icon-only button with no name |
+| `<select>` with `<option>`s | an ARIA-less custom dropdown |
+
+**Run an accessibility checker on your app before installing anything.** The result predicts how well this will work better than anything else you could measure — and the fixes it suggests are worth making regardless of whether you adopt this tool.
+
+### 2. Does your journey need anything on this list?
+
+Not supported yet:
 
-**Windows is untested.** Development and CI run on Linux and macOS. Nothing is known to be broken and reports are welcome (#8).
+- **`iframe` content** — a hosted payment widget is invisible, so an embedded checkout cannot be driven end to end
+- **hover, scroll-to, drag and drop, file upload**
+- **multiple tabs**, and native `alert` / `confirm` dialogs
 
-**Not supported yet:** `iframe` content (so hosted payment widgets like Stripe Elements are invisible — an embedded checkout cannot be driven end to end), hover, scroll-to, drag and drop, file upload, multiple tabs, native `alert`/`confirm` dialogs. Page snapshots are capped at 200 lines by default, so very dense pages are truncated — raise it with `browser.max_snapshot_lines` if your pages need more; truncation is always marked in the snapshot so the model is never misled into thinking it saw the whole page.
+**Windows is untested.** Development and CI run on Linux and macOS. Nothing is known to be broken and reports are welcome ([#8](https://github.com/hamc/blastproof/issues/8)).
 
-**Point it at disposable data.** Within a step, an action that commits — a click, or pressing Enter — is never performed twice: the runner refuses the repeat and tells the agent it already did that. This closes the case that used to produce duplicate records, where a submit answered by a redirect came back to a reset form and the agent, seeing no evidence of its own work, submitted again. It is not a guarantee of zero duplicate writes: an agent that reaches the same effect by a genuinely different route — another control with the same effect — is not caught. Use a seeded database, a staging environment you can reset, or a throwaway account; do not gate on a run against production data.
+If a critical journey needs one of these, that journey stays with your existing test suite. The two can coexist — nothing here replaces what you already have.
 
-`browser.timeout_ms` bounds every wait — resolving a target element from the accessibility tree, and navigation — not only the click or fill performed afterwards. Raise it for an application that is merely slow to hydrate; the trade-off is that a genuinely missing element then takes longer to fail. It never changes how many self-healing retries a step gets — waiting and retrying are deliberately separate.
+### 3. Can you point it at data you can throw away?
 
-Writing each step so it states its own outcome helps here as well as everywhere else: `submit the form, then verify the confirmation shows the reference number` gives the agent something to check, where `click the submit button` leaves it to invent an expectation — and a poor invented expectation is what turns one submission into three.
+**Use a seeded database, a staging environment you can reset, or a throwaway account. Do not gate on a run against production data.**
 
-**This is now load-bearing, not just advisable.** The judge decides whether a step's own outcome holds, using the model's expectation only as the claim offered in support of it — a step that never says what its outcome is gives the judge nothing to anchor on beyond whatever the model happened to check that turn. `verify the confirmation shows the reference number` gives the judge a real question; `verify it worked` does not, and may now fail where a looser judge previously let a true-but-unrelated claim pass it.
+Within a step, an action that commits — a click, or pressing Enter — is never performed twice: the runner refuses the repeat and tells the agent it already did that. This closes the case that used to produce duplicate records, where a submit answered by a redirect came back to a reset form and the agent, seeing no evidence of its own work, submitted again.
+
+It is **not** a guarantee of zero duplicate writes. An agent that reaches the same effect by a genuinely different route — another control that does the same thing — is not caught.
+
+## How it works
+
+<img src="./.github/coverage-flow.svg" width="100%"
+     alt="How a diff becomes a merge decision. In CI, unattended: changed files are matched against the routes: and ignore: globs; matched files contribute affected routes, files matching neither are reported as unclassified and fail the run only under --fail-on-unmapped. Tests declaring an affected route are executed and produce a weighted score, which --min-score gates on. An affected route no test declares is reported as a coverage gap and never fails the run. Separately and manually, outside CI: blastproof plan loads such a route in Chromium, makes one model call, and produces a YAML draft you review, edit and run before committing it.">
+
+**The boundary in the middle is the point.** Everything above it runs unattended on every pull request and ends in an exit code. Everything below it is something you choose to run, on your machine, and review before it lands.
+
+A route no test covers is *reported*, never failed — blocking on it would punish you for an incomplete map instead of teaching you to complete it. Turning that report into a test is the manual half, and the draft it produces is not trusted until a person has read it.
 
 ## Writing tests
 
@@ -70,7 +112,7 @@ steps:
   - complete checkout
 ```
 
-`priority` is P0–P2 (default P1). `tags`, `setup` steps and `auth` are optional — `auth: false` runs the test signed out, which a login test needs. `routes` declares the URLs a test covers, which is what `--impacted` selects on; write route strings consistently, since they compare by exact equality (`/cart` ≠ `/cart/`).
+`priority` is P0–P2 (default P1). `tags`, `setup` steps and `auth` are optional — `auth: false` runs the test signed out, which a login test needs. `routes` declares the URLs a test covers, which is what `--impacted` selects on; write route strings consistently, since they compare by exact equality (`/cart` ≠ `/cart/`). `run` warns to stderr — non-fatal — when a test declares a route no `routes:` mapping declares, since that route contributes nothing to `--impacted` selection.
 
 ### Say what each step should produce
 
@@ -92,6 +134,30 @@ Write steps that end in an observable result — text on the page, a count, a st
 
 **Inline error messages should be plain visible text.** `role="alert"` is read correctly from the accessibility tree and needs no special handling, but note that an alert your page has cleared shows up as an empty element: if a verdict says an alert exists whose content is missing, the message was emptied, not hidden.
 
+### A step that enters a value writes the value
+
+```yaml
+- fill the note field with Order not received   # runs
+- fill the note field                           # cannot run
+```
+
+The agent is **forbidden from inventing values** — one it types must come from the step, from the page, or from an `{{env.*}}` placeholder. But that rule lives in a prompt, and a prompt instructs rather than enforces. Run against a real model, the second step does not fail: the agent makes a value up, fills it, and the step **passes**. `fill the note field` produced "This is a test note." on two runs and "This is a new note" on a third.
+
+That is worse than a failure. The test goes green having verified a value nobody wrote, differing between runs — a passing check over an unspecified input. Closing the gap in the runner is [#57](https://github.com/hamc/blastproof/issues/57); until then, this warning is what stands between you and a green test that means nothing.
+
+`run` warns about it first, on every path, before launching a browser or asking for a key:
+
+```
+Authoring (a step enters a value but names none):
+  Add a note (.blastproof/tests/notes.yaml) step 2:
+      fill the note field
+    → fill the note field with <value>
+```
+
+Non-fatal by default — `--fail-on-authoring` turns it into exit 1 for teams enforcing it in CI. Taking the value from the page is fine and is not flagged: `fill the recipient field with the address shown on the confirmation page`.
+
+**The check reads English only.** A suite written in another language runs exactly as well but is not inspected, and prints no warning saying so — silence from this check means "nothing found in English", never "this suite is clean".
+
 ## Commands
 
 ```bash
@@ -111,43 +177,16 @@ Common flags — `blastproof <command> --help` has the full list:
 | `--url <url>` | Override `base_url` for this run (e.g. a PR preview) |
 | `--min-score <n>` | Gate on a weighted score instead of all-must-pass |
 | `--fail-on-unmapped` | Fail when a changed file matches no `routes:` or `ignore:` glob |
+| `--fail-on-authoring` | Fail when a step enters a value but names none (warns by default) |
 | `--junit [path]` · `--html [path]` | Write reports |
+| `--concurrency <n>` | Run tests at once — [when that is safe](./docs/configuration.md#concurrency--running-tests-at-once) |
 | `--write` | `plan` only — persist drafts instead of previewing |
-| `--max-llm-calls` · `--max-tokens` · `--max-duration` | Bound what a run may spend |
+| `--max-llm-calls` · `--max-tokens` · `--max-duration` | [Bound what a run may spend](./docs/configuration.md#budget--bounding-what-a-run-spends) |
 
 Exit codes: **0** pass, **1** the gate failed, **2** usage or config error.
 
 **Generated drafts are never executed and never affect the score.** An unreviewed model-written test in the merge path fails in two directions: a hallucinated expectation blocks a correct PR, and a credulous one waves a broken change through while looking like coverage. `plan` makes the gap visible with a draft to review; it does not make an uncovered route safe.
 
-## In CI
-
-```yaml
-name: blastproof
-on: pull_request
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0          # required — the diff needs a merge-base
-
-      - run: npm start &          # however your app boots
-
-      - uses: hamc/blastproof@v0.11.0
-        with:
-          version: '0.6.0'        # pin both when this gates merges
-          api-key: ${{ secrets.ANTHROPIC_API_KEY }}
-          base: ${{ github.event.pull_request.base.ref }}
-          min-score: '80'
-          fail-on-unmapped: 'true'
-```
-
-A non-zero exit blocks the merge. The action outputs `score` (0–100, empty when no report was produced) for later steps. Full input list: [`action.yml`](./action.yml).
-
-`fetch-depth: 0` is not optional — the default checkout is shallow and has no merge-base. The action detects this and fails immediately rather than letting it surface as a git error mid-run.
-
 ## Impact mapping
 
 `--impacted` runs only the tests whose `routes:` intersect the routes your diff can affect, mapped from changed files by globs you maintain in `.blastproof/config.yaml`:
@@ -176,6 +215,8 @@ blastproof run --min-score 80    # one failing P2 is tolerated
 
 `--min-score` **replaces** the all-must-pass rule rather than adding to it. Only executed tests count: filtered and unrouted tests are neither numerator nor denominator, and a run that executed nothing scores 100, so a docs-only PR is never blocked. JUnit carries the score as a `<property name="score">`, and unrouted tests appear as `<skipped/>` so the coverage gap shows up in CI rather than vanishing.
 
+Wiring this into a pipeline, with the gating patterns worth knowing: [Running in CI](./docs/ci.md).
+
 ## Without a browser or a key
 
 Half of blastproof is deterministic and free. These need no model, no browser and no network:
@@ -189,103 +230,6 @@ blastproof plan --base main --dry-run                 # affected routes no test
 
 They report affected routes, files nobody has classified, and affected routes no test covers — a coverage-gap report with an exit code, useful even on a repo whose suite is Playwright or Cypress.
 
-## Running tests at once
-
-Tests run one at a time by default. Raise it when your tests can stand it:
-
-```yaml
-concurrency: 4
-```
-
-or `blastproof run --concurrency 4` for a single invocation. On this repository's own suite that takes a run from 156s to 68s — **2.3× faster, for the same 81 model calls.** Parallelism buys wall-clock, not spend.
-
-**The default is 1 on purpose, and raising it is your call to make.** Other test runners default to parallel because their tests are isolated by construction — separate processes, separate fixtures. These are journeys driven against **one running application**, so two tests can see each other's data. A suite is safe to parallelise when its tests do not write state that another test reads.
-
-The test in this repository's own suite that could not run beside itself is a good shape to recognise: it adds a note and then asserts *"one note on file"*. It writes shared server state, and it asserts on a global count. Either alone is a warning; together they mean the test's verdict depends on nothing else touching the application at that moment.
-
-Two practical notes. Four concurrent journeys are four times the traffic against whatever you pointed at — usually fine for a development instance, worth knowing for a shared one. And with several model calls in flight, a `budget:` limit can overshoot by up to the concurrency rather than by a single call, since the calls already sent are allowed to finish.
-
-## Bounding a run
-
-Nothing stops a run by default. `budget:` puts a ceiling on `run`, `plan` and `test` alike — every model call any of them makes is counted:
-
-```yaml
-budget:
-  max_llm_calls: 500
-  max_tokens: 2000000
-  max_duration_s: 900
-```
-
-Each limit is optional; with none set, nothing binds. They count **calls and tokens, not currency** — a price table keyed by model and provider goes stale the day a provider reprices, and a limit that quietly stops meaning what it says is worse than none, because it is trusted.
-
-Exhausting a budget **stops the run; it does not fail a test.** Running out of quota says nothing about the code under review. Unreached tests are reported as `not run`, a third state excluded from the score entirely, and the process exits 1 unconditionally — `--min-score` cannot rescue it, because the tests that finished are whichever ran first, not a representative sample.
-
-**Every run reports what it spent**, so you can size a limit from experience rather than guesswork:
-
-```
-Spent: 82 model call(s), 115407 token(s)
-Score: 100
-```
-
-The figures also land in the JUnit report as `llm_calls` and `llm_tokens`, beside `score`, so a pipeline can trend cost without scraping output. A run stopped by its own budget reports the spend too — that is the case where the number is least guessable. Where a provider reports no token usage, the line says so rather than showing zero.
-
-`--dry-run` reports the ceiling before you spend anything. Read it as a maximum and nothing more: for this repository's own suite it says 735 calls where a real run spends 82. Size a budget from what your runs actually report, not from the ceiling.
-
-For an order of magnitude, this repository's own suite — 7 tests, 31 steps, an authenticated demo shop, `anthropic/claude-haiku-4.5` — spends **about 82 model calls and 115k tokens**, taking 156s serially or 68s at `--concurrency 4`. That is a number you can reproduce (`node examples/demo-app/serve.mjs 4173` and `blastproof run`), not a forecast for your suite: cost scales with steps, page density and how often the agent has to retry. Run yours once and read the `Spent:` line.
-
-## Testing behind a login
-
-Declare a recipe once; blastproof signs in one time per run and reuses that session for every test and for `plan`. Pick exactly one strategy:
-
-```yaml
-# 1) A plain-English journey — form login, or anything a person can click through
-auth:
-  steps:
-    - navigate to /login
-    - fill the email field with {{env.TEST_EMAIL}}
-    - fill the password field with {{env.TEST_PASSWORD}}
-    - submit the login form
-  verify: a signed-in indicator is visible    # optional, strongly recommended
-
-# 2) A session captured by hand — for SSO, MFA or magic links
-auth:
-  storage_state: .blastproof/auth.json
-
-# 3) Static values — for token-based apps
-auth:
-  headers:
-    Authorization: "Bearer {{env.API_TOKEN}}"
-```
-
-**`verify` is worth the extra call.** Without it a wrong password surfaces as every test failing on a login wall — N failures, none naming the cause. Authentication failure exits 2 and never reports as failing tests, because a login you cannot complete says nothing about the code under review.
-
-**A captured session is a credential** — the file holds live cookies. `init` git-ignores it; never commit one.
-
-## LLM providers (BYOK)
-
-**Anthropic** (`ANTHROPIC_API_KEY`), **OpenAI** (`OPENAI_API_KEY`), or **Ollama** (local, no key). Any setting can be overridden from the environment, with precedence **CLI flag > environment > file**:
-
-| variable | overrides |
-| --- | --- |
-| `BLASTPROOF_BASE_URL` | `base_url` — the app under test |
-| `BLASTPROOF_LLM_PROVIDER` | `anthropic` \| `openai` \| `ollama` |
-| `BLASTPROOF_LLM_MODEL` | the model name |
-| `BLASTPROOF_LLM_BASE_URL` | the provider endpoint — *not* the app |
-| `BLASTPROOF_LLM_API_KEY_ENV` | the **name** of the variable holding your key |
-| `BLASTPROOF_MAX_LLM_CALLS` · `BLASTPROOF_MAX_TOKENS` · `BLASTPROOF_MAX_DURATION_S` | the budget fields |
-
-So an OpenAI-compatible gateway needs no file edit:
-
-```bash
-export BLASTPROOF_LLM_PROVIDER=openai
-export BLASTPROOF_LLM_MODEL=anthropic/claude-haiku-4.5
-export BLASTPROOF_LLM_BASE_URL=https://openrouter.ai/api/v1
-export BLASTPROOF_LLM_API_KEY_ENV=OPENROUTER_API_KEY
-blastproof run --impacted --min-score 80
-```
-
-The key itself is never read from a `BLASTPROOF_*` variable — you name *which* variable holds it, so errors can keep naming the one you chose.
-
 ## Trust boundaries
 
 The application under test is not trusted input: its page content reaches the model, so a page that controls its own accessible text can try to influence the agent. Two things constrain that.

package/dist/cli.js

@@ -7,6 +7,20 @@ import { Command, InvalidArgumentError } from "commander";
 import { mkdir, writeFile } from "fs/promises";
 import path from "path";
 import { access } from "fs/promises";
+
+// src/report/errors.ts
+var ReportError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ReportError";
+  }
+};
+function fsReason(error) {
+  if (!(error instanceof Error)) return String(error);
+  return error.message.replace(/^E[A-Z]+:\s*/, "").replace(/,\s+\w+\s+'[^']*'$/, "").trim();
+}
+
+// src/commands/init.ts
 var DEFAULT_CONFIG = `# blastproof configuration
 # Docs: https://github.com/hamc/blastproof
 
@@ -124,14 +138,26 @@ async function exists(file) {
     return false;
   }
 }
+var InitError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InitError";
+  }
+};
 async function writeIfAbsent(file, content, result) {
   if (await exists(file)) {
     result.kept.push(file);
     return;
   }
-  await mkdir(path.dirname(file), { recursive: true });
-  await writeFile(file, content);
-  result.created.push(file);
+  try {
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, content);
+    result.created.push(file);
+  } catch (error) {
+    throw new InitError(
+      `Cannot scaffold ${file}: ${fsReason(error)}. Check that ${path.dirname(file)} is a directory you can write to, not a file.`
+    );
+  }
 }
 async function initProject(cwd = process.cwd()) {
   const result = { created: [], kept: [] };
@@ -1254,7 +1280,7 @@ Rules:
 - Prefer the journey the changed files touch over a generic tour of the page. The changed files tell you which part of the page matters.
 - **The test starts at the application's base URL, not at this route.** Begin with a step that navigates to the route and says what should be visible once it loads \u2014 "navigate to /support and verify the heading "Contact support" is shown". Without it the run opens the home page and every later step looks for controls that are not there.
 - **Every step says what it should produce.** Name what must be true once the step has been carried out, not the action alone: "submit the support form and verify the confirmation page shows the ticket number", never "submit the support form". A step that names an action without an outcome asks the runner to judge whether something happened while looking at the page that succeeding produces \u2014 a submitted form comes back empty, a redirect moves the URL \u2014 and that is the shape behind several real failures.
-- **A step that enters a value writes the value.** "fill the subject field with Order not received", never "enter a subject". The runner is forbidden from inventing values, so a step that does not supply one cannot be carried out.
+- **A step that enters a value writes the value.** "fill the subject field with Order not received", never "enter a subject". The runner is forbidden from inventing values, but a step that supplies none does not fail \u2014 the value gets made up, the step passes, and the test then verifies something nobody wrote.
 - If a step needs a credential or any secret, write it as a placeholder like {{env.TEST_PASSWORD}}. Never write a real or invented password, token or key.
 - Keep the whole test to a handful of steps: one journey, not an exhaustive suite.`;
 }
@@ -1447,7 +1473,7 @@ var TestFileError = class extends Error {
     this.name = "TestFileError";
   }
 };
-function formatIssues2(file, error) {
+function formatIssues2(error) {
   return error.issues.map((issue) => `  - ${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n");
 }
 async function parseTestFile(filePath) {
@@ -1468,7 +1494,7 @@ async function parseTestFile(filePath) {
   const result = testFileSchema.safeParse(data ?? {});
   if (!result.success) {
     throw new TestFileError(`Invalid test file ${filePath}:
-${formatIssues2(filePath, result.error)}`);
+${formatIssues2(result.error)}`);
   }
   return { path: filePath, ...result.data };
 }
@@ -1882,9 +1908,15 @@ ${detail}
 `;
 }
 async function writeHtml(file, html) {
-  await mkdir4(path7.dirname(file), { recursive: true });
-  await writeFile4(file, html, "utf8");
-  return file;
+  try {
+    await mkdir4(path7.dirname(file), { recursive: true });
+    await writeFile4(file, html, "utf8");
+    return file;
+  } catch (error) {
+    throw new ReportError(
+      `Cannot write HTML report to ${file}: ${fsReason(error)}. Check that the path is writable and is not a directory.`
+    );
+  }
 }
 
 // src/report/junit.ts
@@ -1955,9 +1987,45 @@ ${reason}` : reason;
   return lines.join("\n");
 }
 async function writeJUnit(file, xml) {
-  await mkdir5(path8.dirname(file), { recursive: true });
-  await writeFile5(file, xml, "utf8");
-  return file;
+  try {
+    await mkdir5(path8.dirname(file), { recursive: true });
+    await writeFile5(file, xml, "utf8");
+    return file;
+  } catch (error) {
+    throw new ReportError(
+      `Cannot write JUnit report to ${file}: ${fsReason(error)}. Check that the path is writable and is not a directory.`
+    );
+  }
+}
+
+// src/runner/authoring.ts
+var VALUE_VERBS = ["fill", "enter", "type", "input", "set"];
+var LEADING_VALUE_VERB = new RegExp(`^\\s*(?:${VALUE_VERBS.join("|")})\\b`, "i");
+var CONNECTOR_WORDS = ["with", "to", "as", "using", "into", "from", "in"];
+var CONNECTOR_WORD = new RegExp(`\\b(?:${CONNECTOR_WORDS.join("|")})\\b`, "i");
+var CONNECTOR_SYMBOL = /["'`:=]|\{\{env\./i;
+var PHRASAL_IN = new RegExp(`^(\\s*(?:${VALUE_VERBS.join("|")}))\\s+in\\b`, "i");
+function namesNoValue(step) {
+  if (!LEADING_VALUE_VERB.test(step)) return false;
+  const withoutPhrasal = step.replace(PHRASAL_IN, "$1");
+  return !CONNECTOR_WORD.test(withoutPhrasal) && !CONNECTOR_SYMBOL.test(withoutPhrasal);
+}
+function detectMissingValues(tests) {
+  const findings = [];
+  for (const test of tests) {
+    for (const origin of ["setup", "steps"]) {
+      const steps = origin === "setup" ? test.setup ?? [] : test.steps;
+      steps.forEach((step, position) => {
+        if (namesNoValue(step)) {
+          findings.push({ test, origin, index: position + 1, step });
+        }
+      });
+    }
+  }
+  return { findings };
+}
+function suggestValueClause(step) {
+  return `${step.trimEnd()} with <value>`;
 }
 
 // src/runner/pool.ts
@@ -2015,6 +2083,16 @@ function selectImpactedTests(tests, affectedRoutes, filters = { tags: [] }) {
     uncoveredRoutes: affectedRoutes.filter((route) => !covered.has(route))
   };
 }
+function detectRouteDrift(tests, declaredRoutes) {
+  const known = new Set(declaredRoutes);
+  if (known.size === 0) return { drifted: [] };
+  const drifted = [];
+  for (const test of tests) {
+    const unknown = [...new Set(test.routes)].filter((route) => !known.has(route)).sort();
+    if (unknown.length > 0) drifted.push({ test, routes: unknown });
+  }
+  return { drifted };
+}
 
 // src/commands/run.ts
 var EXIT_OK = 0;
@@ -2244,6 +2322,34 @@ function reportUnclassified(options, impact) {
   );
   return true;
 }
+function declaredConfigRoutes(config) {
+  const routes = config.routes ? Object.values(config.routes) : [];
+  return [...new Set(routes.flat())].sort();
+}
+function printRouteDrift(drift, cwd) {
+  if (drift.drifted.length === 0) return;
+  console.error(
+    "Route drift (test routes declared by no routes: mapping \u2014 contribute nothing to --impacted selection):"
+  );
+  for (const { test, routes } of drift.drifted) {
+    console.error(`  ${test.summary} (${path9.relative(cwd, test.path)}): ${routes.join(", ")}`);
+  }
+  console.error("Fix the route typo, or add the route to a routes: mapping in .blastproof/config.yaml.");
+}
+function printAuthoring(result, cwd) {
+  if (result.findings.length === 0) return;
+  console.error("\nAuthoring (a step enters a value but names none):");
+  for (const { test, origin, index, step } of result.findings) {
+    const where = origin === "setup" ? `setup step ${index}` : `step ${index}`;
+    console.error(`  ${test.summary} (${path9.relative(cwd, test.path)}) ${where}:`);
+    console.error(`      ${step}`);
+    console.error(`    \u2192 ${suggestValueClause(step)}`);
+  }
+  console.error(
+    "The runner is forbidden from inventing values, but only by instruction: in practice the model supplies one anyway, the step passes, and the test verifies a value nobody wrote \u2014 a different one on each run."
+  );
+  console.error("Steps are inspected in English only; steps in other languages are not checked.");
+}
 function printDryRun(selected, config, cwd) {
   console.log(`
 Dry run: ${selected.length} test(s) selected, base_url=${config.base_url}`);
@@ -2326,6 +2432,16 @@ async function runCommand(options) {
       throw error;
     }
   }
+  const drift = detectRouteDrift(parsed, declaredConfigRoutes(config));
+  printRouteDrift(drift, options.cwd);
+  const authoring = detectMissingValues(parsed);
+  printAuthoring(authoring, options.cwd);
+  if (options.failOnAuthoring && authoring.findings.length > 0) {
+    console.error(
+      `error: --fail-on-authoring: ${authoring.findings.length} step(s) enter a value but name none.`
+    );
+    return EXIT_FAILED;
+  }
   const selection = impact ? selectImpactedTests(parsed, impact.affectedRoutes, options) : {
     selected: parsed.filter((test) => matchesFilters(test, options)),
     unroutedSkipped: [],
@@ -2720,6 +2836,7 @@ async function testCommand(options) {
     junit: options.junit,
     html: options.html,
     failOnUnmapped: options.failOnUnmapped,
+    failOnAuthoring: options.failOnAuthoring,
     budget
   });
   if (runCode === EXIT_USAGE) return EXIT_USAGE;
@@ -2776,7 +2893,7 @@ function parsePositiveNumber(flag) {
   };
 }
 var program = new Command();
-program.name("blastproof").description("Open-source AI testing agent: plain-English YAML tests executed agentically on a real browser.").version("0.11.0");
+program.name("blastproof").description("Open-source AI testing agent: plain-English YAML tests executed agentically on a real browser.").version("0.12.1");
 program.command("init").description("Scaffold .blastproof/ (config, tests, sample tests) in the current directory").action(async () => {
   try {
     const result = await initProject(process.cwd());
@@ -2791,7 +2908,7 @@ program.command("run").description("Discover and run all tests under .blastproof
   "--min-score <n>",
   "require a weighted score of at least n (0-100); replaces the all-must-pass rule",
   parseMinScore
-).option("--junit [path]", "write a JUnit XML report (default: .blastproof/reports/<session>/junit.xml)").option("--html [path]", "write a self-contained HTML report (default: .blastproof/reports/<session>/report.html)").option("--fail-on-unmapped", "fail when a changed file matches no routes: or ignore: glob").option(
+).option("--junit [path]", "write a JUnit XML report (default: .blastproof/reports/<session>/junit.xml)").option("--html [path]", "write a self-contained HTML report (default: .blastproof/reports/<session>/report.html)").option("--fail-on-unmapped", "fail when a changed file matches no routes: or ignore: glob").option("--fail-on-authoring", "fail when a step enters a value but names none (warns by default)").option(
   "--concurrency <n>",
   "run this many tests at once (overrides config; default 1 \u2014 see the README on when this is safe)",
   parsePositiveInt("--concurrency")
@@ -2823,6 +2940,7 @@ program.command("run").description("Discover and run all tests under .blastproof
         junit: options.junit,
         html: options.html,
         failOnUnmapped: options.failOnUnmapped,
+        failOnAuthoring: options.failOnAuthoring,
         concurrency: options.concurrency,
         maxLlmCalls: options.maxLlmCalls,
         maxTokens: options.maxTokens,
@@ -2873,7 +2991,7 @@ program.command("test").description("Full PR pipeline: run the tests covering th
   "--min-score <n>",
   "require a weighted score of at least n (0-100); replaces the all-must-pass rule",
   parseMinScore
-).option("--junit [path]", "write a JUnit XML report (default: .blastproof/reports/<session>/junit.xml)").option("--html [path]", "write a self-contained HTML report (default: .blastproof/reports/<session>/report.html)").option("--write", "persist generated drafts under .blastproof/tests/ instead of previewing them").option("--fail-on-unmapped", "fail when a changed file matches no routes: or ignore: glob").option(
+).option("--junit [path]", "write a JUnit XML report (default: .blastproof/reports/<session>/junit.xml)").option("--html [path]", "write a self-contained HTML report (default: .blastproof/reports/<session>/report.html)").option("--write", "persist generated drafts under .blastproof/tests/ instead of previewing them").option("--fail-on-unmapped", "fail when a changed file matches no routes: or ignore: glob").option("--fail-on-authoring", "fail when a step enters a value but names none (warns by default)").option(
   "--max-llm-calls <n>",
   "stop the pipeline after this many model calls, shared by both phases (overrides config)",
   parsePositiveInt("--max-llm-calls")
@@ -2897,6 +3015,7 @@ program.command("test").description("Full PR pipeline: run the tests covering th
         html: options.html,
         write: options.write,
         failOnUnmapped: options.failOnUnmapped,
+        failOnAuthoring: options.failOnAuthoring,
         maxLlmCalls: options.maxLlmCalls,
         maxTokens: options.maxTokens,
         maxDuration: options.maxDuration