@asrunjs/asrun 0.8.0 → 0.10.0

package/README.md

@@ -13,8 +13,8 @@ AsRun is a devDependency, not a service. Your profiles, cases, specs and baselin
 - **One spec, every profile.** Each entry in `profiles.yaml` becomes a Playwright project with its own base URL,
   saved login and screenshot baselines. Two accounts of one site give two independent runs.
 - **An AI workflow, not a prompt dump.** `/make-case` turns raw notes into cases, `/explore-case` checks them against
-  the real pages, `/gen-spec` writes the spec, `/heal-spec` repairs it from the last report. Each command ends with
-  `RESULT: ready` or `RESULT: needs-input`, so it works unattended.
+  the real pages, `/gen-spec` writes the spec, `/heal-spec` repairs it from the last report or refines a case and its
+  spec on request. Each command ends with `RESULT: ready` or `RESULT: needs-input`, so it works unattended.
 - **Evidence for every run.** One video per test (browser tabs joined), a trace with every action and request,
   screenshots on failure, and a report that puts the failure first.
 - **Safe by default.** A case is read-only unless it lists environments under `writes`; writing anywhere except
@@ -100,7 +100,8 @@ exempts `@asrunjs/asrun` from pnpm's 24-hour release age, so a fresh release ins
    notes with `/make-case notes.md`. Fill in the steps, what is expected and the exact values.
 4. **Check it against the real pages.** `/explore-case header-logo staging` opens the pages (with your saved session),
    writes what they show into the case and turns what it cannot know into questions. Answer them in the case file, or
-   in the UI's **Answer** sheet, and run it again.
+   in the UI's **Answer** sheet, and run it again. With many profiles, `--profiles a,b` opens only those; a later run
+   with the others adds theirs, and the case keeps both.
 5. **Generate, run, read.** `/gen-spec header-logo staging` writes `tests/header-logo.spec.ts` and fills the case's
    `## Values`. Then:
 
@@ -132,12 +133,13 @@ It is read after the framework skill and before your project rules. Write only w
 
 Rules combine in this order, and a later layer wins where they conflict:
 
-1. `F1`–`F6` of the framework baseline (safety, in every project). They cannot be changed.
+1. `F1`–`F6` and `R2` of the framework baseline (safety, in every project). They cannot be changed.
 2. The framework baseline, `node_modules/@asrunjs/asrun/AGENTS.md`.
 3. The framework skill.
 4. Your override, `.claude/skills/<skill>.md`.
-5. Your own `AGENTS.md` §2: a table of rule ids (`F7`–`F10`) with `narrows` or `replaces`, for example the artifact
-   language.
+5. Your own `AGENTS.md` §2: a table of rule ids (`F7`–`F10`, `R1`, `R3`, `R4`) with `narrows` or `replaces`, for example
+   the artifact language.
+6. A case's `## Rules`: how to run that one case, never what is true.
 
 `pnpm asrun doctor` validates the table and lists the overrides it sees. An update never rewrites your rules:
 `init --force` refuses `AGENTS.md`, `CLAUDE.md` and `.claude/skills/**` without `--reset-rules`. Never edit the

package/bin/asrun.mjs

@@ -26,6 +26,7 @@ const SCRIPTS = {
   cleanup: 'cleanup.js',
   'case:new': 'new-case.js',
   'case:check': 'check-cases.js',
+  'markers:confirm': 'markers-confirm.js',
   'spec:lint': 'lint-specs.js',
   'baselines:review': 'review-baselines.js',
   'pdf:render': 'render-pdf.js',

package/dist/lib/case-doc.d.ts

@@ -183,7 +183,7 @@ export interface CaseQuestion {
     region: TextRange;
 }
 export type MarkerKind = 'confirm' | 'unseen';
-/** `🔍 to be confirmed by QA` and `👁️ not observed`: markers of what was seen but not checked by a person. */
+/** `🔍 to be confirmed` and `👁️ not observed`: markers of what was seen but not checked by a person. */
 export interface CaseMarker {
     kind: MarkerKind;
     /** The marker as written, including its emoji. */
@@ -193,6 +193,21 @@ export interface CaseMarker {
     sentence: string;
     section: string;
     line: number;
+    /**
+     * What a person has to decide, written after the marker's colon inside the same parentheses
+     * (`🔍 to be confirmed: is this the label users see?`). Null in the old form, which only says "shown by QA".
+     */
+    detail: string | null;
+    /** A screenshot a person can look at instead of opening the page again: a `.explore/` image path. */
+    evidence: string | null;
+    /** The marker plus its `: <reason>` and `evidence: <path>` parts: what deleting the marker removes. */
+    removeRange: TextRange;
+}
+/** What a marked line feeds: an assertion, the wording of a step, a method rule, or only context. */
+export interface CaseMarkerFeed {
+    kind: 'assertion' | 'step' | 'rule' | 'note';
+    /** Short text for the panel, e.g. `## Expected` or `a step (the run checks it)`. */
+    label: string;
 }
 export type CaseValues = Record<string, Record<string, unknown>>;
 export interface CaseValuesBlock {
@@ -225,6 +240,12 @@ export interface CaseDocument {
     frontMatter: CaseFrontMatter | null;
     sections: CaseSection[];
     steps: CaseStep[];
+    /**
+     * The top-level bullets of `## Rules`: case-local instructions on *how* to run the case (a page quirk, a mandatory
+     * read-only preparation, a control to avoid). They never define what is true: that stays in Steps, Expected, Values
+     * and Targets (framework baseline `R1`).
+     */
+    rules: CaseBullet[];
     questions: CaseQuestion[];
     markers: CaseMarker[];
     values: CaseValuesBlock | null;
@@ -243,6 +264,18 @@ export declare function endWithBreak(text: string, end: number): number;
 export declare const afterLine: (text: string, line: CaseLine) => number;
 /** The front matter block: its parsed data plus the range of every key, so the panel can edit one key at a time. */
 export declare function parseCaseFrontMatter(text: string): CaseFrontMatter | null;
+/**
+ * What a marked line feeds. Only the first two kinds can be wrong and still pass: an assertion, and the wording of an
+ * expectation. A step, a rule and a note are checked by the run itself, so a person does not have to re-read them.
+ */
+export declare function markerFeed(doc: CaseDocument, marker: CaseMarker): CaseMarkerFeed;
+/** How many markers of a case feed an assertion, i.e. how many are worth a person's attention. */
+export declare function assertionMarkerCount(doc: CaseDocument): number;
+/**
+ * The line a marker sits on, without the marker, its reason and its evidence: the sentence a person actually reads.
+ * The `(observed on ...)` part stays, because where it was seen is the context they need.
+ */
+export declare function markerSentence(text: string, marker: CaseMarker): string;
 /** A prose section (`## Goal`, `## Notes`): the panel renders it read-only and reveals a line on click. */
 export declare function parseProse(text: string, name: string): CaseProse | null;
 /** The top-level bullets of a list section, with the blocks (a wrapped text, a TODO block) that belong to each. */
@@ -263,11 +296,15 @@ export declare function setQuestionAnswer(text: string, question: CaseQuestion,
 /** Accepts the suggestion: deletes the whole question block, the answer line included. */
 export declare function acceptQuestion(text: string, question: CaseQuestion): string;
 /**
- * Removes a `🔍 to be confirmed by QA` / `👁️ not observed` marker. When the marker is the only content of its
- * parentheses, the parentheses go too (`(👁️ not observed)`); otherwise the marker and one separator leave
- * `(observed, 🔍 to be confirmed by QA)` as `(observed)`.
+ * What deleting a `🔍 to be confirmed` / `👁️ not observed` marker removes. When the marker is the only content
+ * of its parentheses, the parentheses go too (`(👁️ not observed)`); otherwise the marker and one separator leave
+ * `(observed, 🔍 to be confirmed)` as `(observed)`.
  */
+export declare function markerEdits(text: string, marker: CaseMarker): TextEdit;
+/** Removes one marker, its punctuation and, when it was alone, its parentheses. */
 export declare function removeMarker(text: string, marker: CaseMarker): string;
+/** Removes several markers in one edit, so the panel can confirm a whole list with one undo step. */
+export declare function removeMarkers(text: string, markers: CaseMarker[]): string;
 /** Sets one value of one profile; `null` removes it (an empty cell in the panel means "not set here"). */
 export declare function setCaseValue(text: string, profile: string, key: string, value: string | null): string;
 /** Adds a key to the `default` values of the case. */

package/dist/lib/case-doc.js

@@ -465,8 +465,41 @@ function parseQuestions(text, sections) {
 }
 /* Kept in step with `ui/web/src/lib/highlight-keywords.ts` (same words, same emoji prefixes). */
 const MARKER_RE = /(?:\u{1F50D}\uFE0F?[ \t]*)?(?:\bto be confirmed(?:\s+by\s+QA)?\b|\bTBC\b|\bTBD\b|\bneeds?\s+confirmation\b)|(?:\u{1F441}\uFE0F?[ \t]*)?\bnot observed\b/giu;
-function parseMarkers(text, sections) {
+/** A screenshot named in the same parentheses as a marker: the evidence a person looks at instead of the page. */
+const MARKER_EVIDENCE_RE = /\bevidence:[ \t]*([^\s;)]+\.(?:png|jpe?g|webp))/i;
+/**
+ * What the parentheses around a marker say beyond the marker itself: the one thing a person has to decide (`: ...`)
+ * and the evidence image (`evidence: <path>`). Both are optional, so the old `(observed, 🔍 to be confirmed by QA)`
+ * still reads; it just says less. `removeEnd` runs to the end of the reason and the evidence, so deleting the marker
+ * leaves the observation alone.
+ */
+function markerParts(text, start, end) {
+    const open = text.lastIndexOf('(', start);
+    const close = text.indexOf(')', end);
+    if (open < 0 || close < 0 || close < end || /[\r\n]/.test(text.slice(open, close))) {
+        return { detail: null, evidence: null, removeEnd: end };
+    }
+    const inside = text.slice(open + 1, close);
+    const evidenceMatch = MARKER_EVIDENCE_RE.exec(inside);
+    const evidence = evidenceMatch?.[1] ?? null;
+    const tail = text.slice(end, close);
+    const colon = /^[ \t]*:[ \t]*/.exec(tail);
+    const raw = colon ? tail.slice(colon[0].length) : '';
+    const detail = colon ? raw.replace(/[;,][ \t]*evidence:[\s\S]*$/i, '').trim() : '';
+    const removeEnd = evidenceMatch
+        ? open + 1 + evidenceMatch.index + evidenceMatch[0].length
+        : colon
+            ? end + colon[0].length + raw.trimEnd().length
+            : end;
+    return { detail: detail === '' ? null : detail, evidence, removeEnd };
+}
+/**
+ * Markers of `text`. A marker written inside a question block is not one: the question already says that a person has
+ * to decide, and counting it twice would put the same claim in "Open questions" and "To confirm".
+ */
+function parseMarkers(text, sections, questions) {
     const markers = [];
+    const blocks = questions.map((question) => question.blockRange);
     let fenced = false;
     for (const line of splitLines(text)) {
         if (isFence(line.text)) {
@@ -478,18 +511,59 @@ function parseMarkers(text, sections) {
         for (const match of line.text.matchAll(MARKER_RE)) {
             if (match[0] === '')
                 continue;
+            const start = line.start + (match.index ?? 0);
+            const end = start + match[0].length;
+            if (blocks.some((block) => start >= block.start && start <= block.end))
+                continue;
+            const parts = markerParts(text, start, end);
             markers.push({
                 kind: /not observed/i.test(match[0]) ? 'unseen' : 'confirm',
                 text: match[0],
-                range: { start: line.start + (match.index ?? 0), end: line.start + (match.index ?? 0) + match[0].length },
+                range: { start, end },
+                removeRange: { start, end: parts.removeEnd },
                 sentence: line.text.trim(),
                 section: sectionAt(sections, line.start),
                 line: line.number,
+                detail: parts.detail,
+                evidence: parts.evidence,
             });
         }
     }
     return markers;
 }
+/**
+ * What a marked line feeds. Only the first two kinds can be wrong and still pass: an assertion, and the wording of an
+ * expectation. A step, a rule and a note are checked by the run itself, so a person does not have to re-read them.
+ */
+export function markerFeed(doc, marker) {
+    if (marker.section === 'Values' || marker.section === 'Expected' || marker.section === 'Visual checks') {
+        return { kind: 'assertion', label: `## ${marker.section}` };
+    }
+    if (marker.section === 'Steps')
+        return { kind: 'step', label: 'a step (the run checks it)' };
+    if (marker.section === 'Rules')
+        return { kind: 'rule', label: 'a method rule (never an assertion)' };
+    return { kind: 'note', label: marker.section === '' ? 'the case' : `## ${marker.section}` };
+}
+/** How many markers of a case feed an assertion, i.e. how many are worth a person's attention. */
+export function assertionMarkerCount(doc) {
+    return doc.markers.filter((marker) => markerFeed(doc, marker).kind === 'assertion').length;
+}
+/**
+ * The line a marker sits on, without the marker, its reason and its evidence: the sentence a person actually reads.
+ * The `(observed on ...)` part stays, because where it was seen is the context they need.
+ */
+export function markerSentence(text, marker) {
+    const lineStart = text.lastIndexOf('\n', marker.range.start) + 1;
+    const lineBreak = text.indexOf('\n', marker.range.start);
+    const lineEnd = lineBreak === -1 ? text.length : lineBreak;
+    return (text.slice(lineStart, marker.range.start) + text.slice(marker.removeRange.end, lineEnd))
+        .replace(/^[ \t]*(?:[-*+]|\d+\.)[ \t]+/, '')
+        .replace(/[,;][ \t]*\)/g, ')')
+        .replace(/\([ \t]*\)/g, '')
+        .replace(/[ \t]{2,}/g, ' ')
+        .trim();
+}
 const VALUES_OPEN_RE = /^[ \t]*```ya?ml[ \t]*$/i;
 const VALUES_CLOSE_RE = /^[ \t]*```[ \t]*$/;
 const isPlaceholderValue = (value) => value === null || value === undefined || value === '' || (typeof value === 'string' && /^\s*TODO\b/i.test(value));
@@ -801,13 +875,16 @@ export function caseMetaProblems(id, data, knownEnvs, label = 'case document') {
 export function parseCaseDocument(text) {
     const lines = splitLines(text);
     const sections = sectionsOf(text, lines);
+    // Questions first: a marker written inside one belongs to that question, not to "To confirm".
+    const questions = parseQuestions(text, sections);
     return {
         text,
         frontMatter: parseCaseFrontMatter(text),
         sections,
         steps: parseSteps(text, sections.find((section) => section.name === 'Steps')),
-        questions: parseQuestions(text, sections),
-        markers: parseMarkers(text, sections),
+        rules: parseBullets(text, 'Rules'),
+        questions,
+        markers: parseMarkers(text, sections, questions),
         values: parseValues(text, sections.find((section) => section.name === 'Values')),
         targets: parseTargetCards(text),
         inputs: parseInputs(text, sections.find((section) => section.name === 'Inputs')),
@@ -877,27 +954,42 @@ export function acceptQuestion(text, question) {
     return patchText(text, [{ start: question.blockRange.start, end: endWithBreak(text, question.blockRange.end), text: '' }]);
 }
 /**
- * Removes a `🔍 to be confirmed by QA` / `👁️ not observed` marker. When the marker is the only content of its
- * parentheses, the parentheses go too (`(👁️ not observed)`); otherwise the marker and one separator leave
- * `(observed, 🔍 to be confirmed by QA)` as `(observed)`.
+ * What deleting a `🔍 to be confirmed` / `👁️ not observed` marker removes. When the marker is the only content
+ * of its parentheses, the parentheses go too (`(👁️ not observed)`); otherwise the marker and one separator leave
+ * `(observed, 🔍 to be confirmed)` as `(observed)`.
  */
-export function removeMarker(text, marker) {
-    const open = text.lastIndexOf('(', marker.range.start);
-    const close = text.indexOf(')', marker.range.end);
+export function markerEdits(text, marker) {
+    const start = marker.range.start;
+    const markerEnd = marker.removeRange.end;
+    const open = text.lastIndexOf('(', start);
+    const close = text.indexOf(')', markerEnd);
     if (open >= 0 && close >= 0 && !/[\r\n]/.test(text.slice(open, close))) {
-        const rest = text.slice(open + 1, marker.range.start) + text.slice(marker.range.end, close);
+        const rest = text.slice(open + 1, start) + text.slice(markerEnd, close);
         if (/^[\s,;:—-]*$/.test(rest)) {
             const before = text[open - 1] === ' ' && /[.,;:!?]/.test(text[close + 1] ?? '') ? open - 1 : open;
-            return patchText(text, [{ start: before, end: close + 1, text: '' }]);
+            return { start: before, end: close + 1, text: '' };
         }
     }
-    const lead = /(?:[ \t]*[,;][ \t]*|[ \t]+)$/.exec(text.slice(0, marker.range.start));
+    const lead = /(?:[ \t]*[,;][ \t]*|[ \t]+)$/.exec(text.slice(0, start));
     if (lead) {
-        return patchText(text, [{ start: marker.range.start - lead[0].length, end: marker.range.end, text: '' }]);
+        return { start: start - lead[0].length, end: markerEnd, text: '' };
     }
-    const trail = /^[ \t]+/.exec(text.slice(marker.range.end));
-    const end = trail ? marker.range.end + trail[0].length : marker.range.end;
-    return patchText(text, [{ start: marker.range.start, end, text: '' }]);
+    const trail = /^[ \t]+/.exec(text.slice(markerEnd));
+    const end = trail ? markerEnd + trail[0].length : markerEnd;
+    return { start, end, text: '' };
+}
+/** Removes one marker, its punctuation and, when it was alone, its parentheses. */
+export function removeMarker(text, marker) {
+    return patchText(text, [markerEdits(text, marker)]);
+}
+/** Removes several markers in one edit, so the panel can confirm a whole list with one undo step. */
+export function removeMarkers(text, markers) {
+    if (markers.length === 0)
+        return text;
+    const edits = [...markers]
+        .sort((a, b) => b.range.start - a.range.start)
+        .map((marker) => markerEdits(text, marker));
+    return patchText(text, edits);
 }
 function replaceValues(text, block, values) {
     const yaml = stringifyYaml(values, { lineWidth: 0 }).replace(/\r?\n/g, newlineOf(text));

package/dist/scripts/check-cases.js

@@ -1,11 +1,35 @@
 import fs from 'node:fs';
 import { CASES_DIR } from '../lib/paths.js';
 import { listCaseFileIds, readCaseMeta } from '../lib/cases.js';
-import { parseCaseDocument } from '../lib/case-doc.js';
+import { parseCaseDocument, splitLines } from '../lib/case-doc.js';
 import path from 'node:path';
 import { ROOT } from '../lib/paths.js';
 import { checksNeedingTarget, parseTargets, readCaseText, REQUIRED_FIELDS, targetRefsIn } from '../lib/targets.js';
 import { parseCaseValues } from '../lib/values.js';
+const LIST_ITEM = /^[ \t]*(?:[-*+]|\d+\.)[ \t]+\S/;
+const HEADING = /^##[ \t]+\S/;
+/** The words the panel and `case:check` treat as a marker: one claim carries one signal. */
+const MARKER_WORD = /\b(?:to be confirmed(?:\s+by\s+QA)?|TBC|TBD|not observed)\b/i;
+const indentOf = (text) => text.length - text.trimStart().length;
+/**
+ * The line a question immediately hangs under: the nearest line above it that is indented less and can carry text.
+ * `null` when that line is a paragraph (the model extends a paragraph upwards on purpose) or nothing qualifies.
+ */
+function immediateAnchor(lines, questionLine, indent) {
+    const at = lines.findIndex((line) => line.number === questionLine);
+    for (let index = at - 1; index >= 0; index--) {
+        const text = lines[index].text;
+        if (text.trim() === '' || HEADING.test(text) || /^[ \t]*```/.test(text))
+            return null;
+        if (indentOf(text) >= indent)
+            continue;
+        // Another question at a shallower depth is not the sentence this one stands for.
+        if (/^[ \t]*[-*+][ \t]+(?:\u{1F6AB}|\u{2753}|\u270D)/u.test(text))
+            continue;
+        return LIST_ITEM.test(text) ? lines[index].number : null;
+    }
+    return null;
+}
 /** Step numbers of the lines marked `[input]` or `[writes]` in "## Steps" (a person does them), and the numbers that have a `- Recipe:` line under them (or an old "## Inputs" line). */
 function inputSteps(id) {
     const doc = parseCaseDocument(fs.readFileSync(path.join(CASES_DIR, `${id}.md`), 'utf8'));
@@ -41,6 +65,11 @@ function questionProblems(id) {
         if (step && question.indent < 4) {
             warnings.push(`the question on line ${question.line} is indented by ${question.indent} space(s) under step ${step.number}; 4 renders it inside the step`);
         }
+        const anchor = immediateAnchor(splitLines(doc.text), question.line, question.indent);
+        if (anchor !== null && anchor !== question.parent.line) {
+            const above = splitLines(doc.text).find((line) => line.number === anchor)?.text.trim() ?? '';
+            warnings.push(`the question on line ${question.line} hangs under "${above.slice(0, 80)}", but the panel shows "${question.parent.text.slice(0, 80)}" as the text above it; indent it under that sentence or lift that sentence to a top-level bullet`);
+        }
     }
     for (const step of doc.steps) {
         if (step.recipes.length === 0)
@@ -62,6 +91,58 @@ function questionProblems(id) {
     }
     return warnings;
 }
+/**
+ * Problems with the markers (`🔍 to be confirmed by QA`, `👁️ not observed`): one claim carries one signal, and a
+ * marker says what a person has to decide. A marker inside a question block is a failure; the old form without a
+ * "why" is a warning, so old cases keep working.
+ */
+function markerProblems(id) {
+    const text = fs.readFileSync(path.join(CASES_DIR, `${id}.md`), 'utf8');
+    const doc = parseCaseDocument(text);
+    const fail = [];
+    const warn = [];
+    for (const question of doc.questions) {
+        const end = question.hasAnswerLine ? question.answerRange.start : question.blockRange.end;
+        if (MARKER_WORD.test(text.slice(question.blockRange.start, end))) {
+            fail.push(`the question on line ${question.line} holds a marker word ("to be confirmed" / "not observed"): one claim carries one signal, so keep the question and drop the marker`);
+        }
+    }
+    if (doc.values?.hasBlock && MARKER_WORD.test(text.slice(doc.values.range.start, doc.values.range.end))) {
+        fail.push('a marker inside the "## Values" yaml block would become part of the expected value: put it on the prose line above the block');
+    }
+    const parentLines = new Set(doc.questions.map((question) => question.parent?.line).filter((line) => line !== undefined));
+    for (const marker of doc.markers) {
+        if (parentLines.has(marker.line)) {
+            fail.push(`line ${marker.line} carries a marker and a question under it: keep the question (drop the marker) or the marker (drop the question)`);
+        }
+        if (marker.detail === null) {
+            warn.push(`the marker on line ${marker.line} does not say what a person must confirm; write "🔍 to be confirmed: <the one thing to decide>"` +
+                (marker.evidence === null
+                    ? ', plus "evidence: .explore/observations/<case-id>/<image>.png" when a screenshot says it better'
+                    : ''));
+        }
+    }
+    return { fail, warn };
+}
+/**
+ * Problems with the `## Rules` bullets: a rule may name the step it belongs to (`Step 3:`, `Before step 3:` or
+ * `After step 3:`). A reference to a step the case does not have is a failure, because the rule would silently lose its
+ * scope. An unprefixed rule applies to the whole case and is always valid.
+ */
+function ruleProblems(id) {
+    const doc = parseCaseDocument(fs.readFileSync(path.join(CASES_DIR, `${id}.md`), 'utf8'));
+    const failures = [];
+    for (const rule of doc.rules) {
+        const match = /^(?:(?:before|after)[ \t]+)?step[ \t]+(\d+)\b/i.exec(rule.text);
+        if (!match)
+            continue;
+        const number = Number(match[1]);
+        if (!doc.steps.some((step) => step.number === number)) {
+            failures.push(`the rule on line ${rule.line} refers to step ${number}, which this case does not have`);
+        }
+    }
+    return failures;
+}
 /**
  * Warnings for the old layout. `## Data` and `## Inputs` are deprecated: the one-sentence summary belongs in
  * `writes-note`, the cleanup in steps, and a person's recipe under its step. Cases keep working, so this never fails.
@@ -131,6 +212,8 @@ for (const id of ids) {
             console.log(`warn ${id}: ${message}`);
         for (const message of targets.fail)
             throw new Error(message);
+        for (const message of ruleProblems(id))
+            throw new Error(message);
         const { marked, recorded } = inputSteps(id);
         const missing = marked.filter((step) => !recorded.includes(step));
         if (missing.length > 0) {
@@ -140,6 +223,11 @@ for (const id of ids) {
             console.log(`warn ${id}: ${message}`);
         for (const message of questionProblems(id))
             console.log(`warn ${id}: ${message}`);
+        const markers = markerProblems(id);
+        for (const message of markers.warn)
+            console.log(`warn ${id}: ${message}`);
+        for (const message of markers.fail)
+            throw new Error(message);
     }
     catch (error) {
         problems++;

package/dist/scripts/doctor.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { loadProfiles, listEnvs, PROFILES_FILE } from '../lib/profiles.js';
 import { FRAMEWORK_ROOT, ROOT, SKILLS_DIR } from '../lib/paths.js';
 import { spawnTarget } from '../lib/command.js';
@@ -25,17 +26,20 @@ function read(file) {
 function nonNegotiableRules() {
     const ids = new Set();
     for (const line of (read(path.join(FRAMEWORK_ROOT, 'AGENTS.md')) ?? '').split('\n')) {
-        const match = /^- \*\*(F\d+)\b/.exec(line.trim());
+        const match = /^- \*\*([A-Z]\d+)\b/.exec(line.trim());
         if (match && line.includes('[non-negotiable]'))
             ids.add(match[1]);
     }
     return ids;
 }
-/** Every rule id the framework baseline defines (`F1`..`F10`), so a project cannot name one that does not exist. */
+/**
+ * Every rule id the framework baseline defines (`F1`..`F10`, `B1`..`B4`, `A1`..`A6`, `R1`..`R4`), so a project cannot
+ * name one that does not exist.
+ */
 function frameworkRuleIds() {
     const ids = new Set();
     for (const line of (read(path.join(FRAMEWORK_ROOT, 'AGENTS.md')) ?? '').split('\n')) {
-        const match = /^- \*\*(F\d+)\b/.exec(line.trim());
+        const match = /^- \*\*([A-Z]\d+)\b/.exec(line.trim());
         if (match)
             ids.add(match[1]);
     }
@@ -70,6 +74,38 @@ function staleDistFiles() {
     walk('scripts');
     return stale;
 }
+/**
+ * The browser tools the workspace's `playwright-test` MCP can actually run, and the Playwright version it comes from.
+ *
+ * `playwright run-test-mcp-server` advertises every browser tool Playwright has, but a call runs in a paused test whose
+ * backend installs only the `core` and `testing` capabilities and skips the `skillOnly` tools; anything else answers
+ * `Tool "<name>" not found`. The skills' `references/tools.md` documents the substitutes, so this tells a person when
+ * an upgrade moved a tool out of that set before an exploration discovers it. `null` when the install cannot be
+ * inspected (then the check says nothing rather than guessing).
+ */
+function runnableBrowserTools() {
+    try {
+        const requireFrom = createRequire(path.join(ROOT, 'package.json'));
+        const testManifest = requireFrom.resolve('@playwright/test/package.json');
+        const playwrightManifest = requireFrom.resolve('playwright/package.json', { paths: [path.dirname(testManifest)] });
+        const coreManifest = requireFrom.resolve('playwright-core/package.json', { paths: [path.dirname(playwrightManifest)] });
+        const bundle = requireFrom(path.join(path.dirname(coreManifest), 'lib', 'coreBundle.js'));
+        const tools = bundle.tools?.filteredTools?.({ capabilities: ['testing'] });
+        if (!tools)
+            return null;
+        const version = JSON.parse(read(playwrightManifest) ?? '{}').version ?? 'unknown';
+        return { version, tools: tools.map((tool) => tool.schema.name) };
+    }
+    catch {
+        return null;
+    }
+}
+/** Every tool the skills' `tools.md` lists under `## Runnable`, i.e. the ones an exploration is told to use. */
+function documentedBrowserTools() {
+    const text = read(path.join(SKILLS_DIR, 'exploring-cases', 'references', 'tools.md')) ?? '';
+    const section = /^## Runnable\n([\s\S]*?)^## /m.exec(text)?.[1] ?? '';
+    return [...new Set(section.match(/browser_[a-z0-9_]+/g) ?? [])];
+}
 export async function main(args) {
     if (args.includes('--help')) {
         console.log('Usage: pnpm asrun doctor');
@@ -326,6 +362,17 @@ export async function main(args) {
             warnings.push(`${file} starts the MCP server with "${command}", which does not exist: run "pnpm asrun init --force ${file}".`);
         }
     }
+    // The browser tools the `playwright-test` MCP can really run: the skills' `tools.md` must not name one it cannot.
+    const runnable = runnableBrowserTools();
+    if (runnable !== null) {
+        facts.push(`playwright-test mcp:  ${runnable.tools.length} runnable browser tools (Playwright ${runnable.version})`);
+        const missing = documentedBrowserTools().filter((tool) => !runnable.tools.includes(tool));
+        if (missing.length > 0) {
+            warnings.push(`Playwright ${runnable.version} cannot run ${missing.join(', ')} in this MCP, but ` +
+                '.claude/skills/exploring-cases/references/tools.md names it as runnable: the test-runner backend changed ' +
+                'its capabilities. Update that file (and the substitute for each tool) before exploring.');
+        }
+    }
     const settings = read(path.join(ROOT, '.claude', 'settings.json'));
     if (settings === null) {
         warnings.push('.claude/settings.json is missing: run "pnpm asrun init" (Claude Code needs its sandbox exclusions for pnpm asrun).');

package/dist/scripts/markers-confirm.d.ts

@@ -0,0 +1 @@
+export {};