scenescout 3.11.0 → 3.12.0

package/dist/engine/check.js

@@ -81,7 +81,31 @@ export const CHECK_RULES = {
         help: "A step of a flow saved in .scenescout/flows could not be done, or what it expected was not there. The evidence names the flow, the step and what happened instead.",
     },
 };
-export const CHECK_RULE_IDS = Object.keys(CHECK_RULES);
+/**
+ * Rules whose measurement is exact and whose meaning depends on a convention
+ * of the project the check cannot see. SceneScout is used against any app, so
+ * it does not decide those conventions: these are listed as "worth a look",
+ * each naming the convention that would make it a defect, and never counted,
+ * given a severity or gated on, at any --fail-on. SARIF reports them at level
+ * "note". `convention` finishes the sentence "a defect only if your project
+ * uses …". --ignore takes them like any other rule.
+ */
+export const WORTH_A_LOOK_RULES = {
+    "off-grid-spacing": {
+        title: "Spacing off a 4px grid",
+        help: "More than a fifth of the page's paddings or vertical margins are not multiples of 4px. That matters where a project keeps a 4px spacing scale, and not where it uses another scale or none.",
+        convention: "a 4px spacing scale",
+    },
+    "indistinct-link": {
+        title: "Link styled like body text",
+        help: "Links with no underline, in the same colour as the page's body text. In running text a reader cannot tell them from the text around them; in navigation this styling is common, and the check cannot tell the two apart.",
+        convention: "a visible link style (an underline or a distinct colour) wherever links appear, navigation included",
+    },
+};
+export const CHECK_RULE_IDS = [...Object.keys(CHECK_RULES), ...Object.keys(WORTH_A_LOOK_RULES)];
+export function isWorthALookRule(rule) {
+    return Object.prototype.hasOwnProperty.call(WORTH_A_LOOK_RULES, rule);
+}
 const SEVERITY_RANK = { high: 0, medium: 1, low: 2 };
 /** Snapshot refs (`e12`) are numbered per run; evidence carrying them would never match itself twice. */
 function stripRefs(line) {
@@ -145,27 +169,36 @@ export function geometryRule(line) {
  * oracles caught while it ran. The second kind goes through the same rules as
  * a crawled page's, so a request that fails on load and again inside a flow is
  * one issue, not two.
+ *
+ * A fact under a worth-a-look rule goes to `worthALook` instead, deduplicated
+ * the same way; the two lists never share an entry.
  */
-export function issuesFromRoutes(routes, origin, ignore = [], flows = []) {
+export function checkFindings(routes, origin, ignore = [], flows = []) {
     const byKey = new Map();
+    const looks = new Map();
     const add = (rule, evidence, route, opts = {}) => {
         if (ignore.includes(rule))
             return;
         const clean = redactSecrets(withoutOrigin(evidence, origin)).slice(0, 300);
         const key = `${rule}\u0000${clean}`;
-        const found = byKey.get(key);
+        const found = byKey.get(key) ?? looks.get(key);
         if (found) {
             if (!found.routes.includes(route))
                 found.routes.push(route);
             return;
         }
+        const fingerprint = createHash("sha256").update(key).digest("hex").slice(0, 32);
+        if (isWorthALookRule(rule)) {
+            looks.set(key, { rule, evidence: clean, routes: [route], convention: WORTH_A_LOOK_RULES[rule].convention, fingerprint });
+            return;
+        }
         byKey.set(key, {
             rule,
             severity: opts.embed ? "medium" : (opts.severity ?? CHECK_RULES[rule].severity),
             evidence: clean,
             routes: [route],
             ...(opts.embed ? { embed: opts.embed } : {}),
-            fingerprint: createHash("sha256").update(key).digest("hex").slice(0, 32),
+            fingerprint,
         });
     };
     for (const r of routes) {
@@ -206,7 +239,14 @@ export function issuesFromRoutes(routes, origin, ignore = [], flows = []) {
         if (f.outcome.status === "failed")
             add("flow-step-failed", flowStepEvidence(f), f.outcome.path);
     }
-    return [...byKey.values()].sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || a.rule.localeCompare(b.rule));
+    return {
+        issues: [...byKey.values()].sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || a.rule.localeCompare(b.rule)),
+        worthALook: [...looks.values()].sort((a, b) => a.rule.localeCompare(b.rule)),
+    };
+}
+/** The defect tier of `checkFindings`: what counts, and what the gate reads. */
+export function issuesFromRoutes(routes, origin, ignore = [], flows = []) {
+    return checkFindings(routes, origin, ignore, flows).issues;
 }
 /**
  * Why a check has nothing to give a verdict on, or null when it measured the
@@ -383,7 +423,7 @@ export function parseCheckArgs(args, cwd) {
     if (paths?.some((p) => !p.startsWith("/")))
         return { ok: false, error: "--paths are paths on the app, each starting with /" };
     const ignore = list(flags.get("ignore")) ?? [];
-    const unknownRules = ignore.filter((r) => !(r in CHECK_RULES));
+    const unknownRules = ignore.filter((r) => !CHECK_RULE_IDS.includes(r));
     if (unknownRules.length > 0)
         return { ok: false, error: `unknown rule(s) in --ignore: ${unknownRules.join(", ")}. Rules: ${CHECK_RULE_IDS.join(", ")}` };
     const retest = flags.get("retest") ?? "on";
@@ -489,8 +529,17 @@ const RETEST_SARIF_RULE = {
     help: { text: "A finding an earlier run filed and left open failed the same way when its page loaded again. It gates according to --gate-retests." },
     defaultConfiguration: { level: "error" },
 };
+function sarifLocation(route) {
+    return route === "(shared chrome)"
+        ? {
+            physicalLocation: { artifactLocation: { uri: "", uriBaseId: "APP" } },
+            message: { text: "the app's shared shell, on every page that renders it" },
+        }
+        : { physicalLocation: { artifactLocation: { uri: route.replace(/^\//, ""), uriBaseId: "APP" } } };
+}
 export function toSarif(result, toolVersion) {
     const used = [...new Set(result.issues.map((i) => i.rule))];
+    const lookRules = [...new Set(result.worthALook.map((o) => o.rule))];
     const base = new URL(result.url);
     const reproducing = retestGateFailures(result);
     const refused = result.flows.filter((f) => f.outcome.status === "refused");
@@ -500,14 +549,20 @@ export function toSarif(result, toolVersion) {
         message: {
             text: `${CHECK_RULES[i.rule].title}: ${i.evidence}${i.routes.length > 1 ? ` (on ${i.routes.length} routes)` : ""}${i.embed ? ` (in an embed of ${i.embed})` : ""}`,
         },
-        locations: i.routes.slice(0, 10).map((r) => r === "(shared chrome)"
-            ? {
-                physicalLocation: { artifactLocation: { uri: "", uriBaseId: "APP" } },
-                message: { text: "the app's shared shell, on every page that renders it" },
-            }
-            : { physicalLocation: { artifactLocation: { uri: r.replace(/^\//, ""), uriBaseId: "APP" } } }),
+        locations: i.routes.slice(0, 10).map(sarifLocation),
         partialFingerprints: { "scenescoutCheck/v1": i.fingerprint },
     }));
+    // Always "note", whatever --fail-on says: a result a code-scanning dashboard shows, never one that reads as an error.
+    const lookResults = result.worthALook.map((o) => ({
+        ruleId: o.rule,
+        level: "note",
+        message: {
+            text: `Worth a look — ${WORTH_A_LOOK_RULES[o.rule].title}: ${o.evidence}${o.routes.length > 1 ? ` (on ${o.routes.length} routes)` : ""}. A defect only if your project uses ${o.convention}.`,
+        },
+        locations: o.routes.slice(0, 10).map(sarifLocation),
+        partialFingerprints: { "scenescoutCheck/v1": o.fingerprint },
+        properties: { tier: "worth-a-look", convention: o.convention },
+    }));
     // Only the re-tests that fail the gate are results: a reviewer reading code scanning sees what failed it.
     const retestResults = reproducing.map((r) => ({
         ruleId: RETEST_SARIF_RULE.id,
@@ -537,6 +592,14 @@ export function toSarif(result, toolVersion) {
                                 help: { text: CHECK_RULES[id].help },
                                 defaultConfiguration: { level: SARIF_LEVEL[CHECK_RULES[id].severity] },
                             })),
+                            ...lookRules.map((id) => ({
+                                id,
+                                name: WORTH_A_LOOK_RULES[id].title,
+                                shortDescription: { text: WORTH_A_LOOK_RULES[id].title },
+                                help: { text: `${WORTH_A_LOOK_RULES[id].help} Worth a look: a defect only if your project uses ${WORTH_A_LOOK_RULES[id].convention}.` },
+                                defaultConfiguration: { level: "note" },
+                                properties: { tags: ["worth-a-look"] },
+                            })),
                             ...(reproducing.length > 0 ? [RETEST_SARIF_RULE] : []),
                         ],
                     },
@@ -553,7 +616,7 @@ export function toSarif(result, toolVersion) {
                     },
                 ],
                 originalUriBaseIds: { APP: { uri: `${base.origin}/` } },
-                results: [...issueResults, ...retestResults],
+                results: [...issueResults, ...lookResults, ...retestResults],
             },
         ],
     };
@@ -596,7 +659,8 @@ export function formatCheck(result) {
         (passed
             ? `${couldNotRun > 0 ? "passed" : "**PASSED**"} — ${counts.high} high · ${counts.medium} medium · ${counts.low} low`
             : `${couldNotRun > 0 ? "failed" : "**FAILED**"} — ${failingText} · ${counts.high} high · ${counts.medium} medium · ${counts.low} low`) +
-        (unaudited > 0 ? ` · design not measured on ${unaudited} route(s)` : ""));
+        (unaudited > 0 ? ` · design not measured on ${unaudited} route(s)` : "") +
+        (result.worthALook.length > 0 ? ` · ${result.worthALook.length} worth a look, never gated` : ""));
     // Right under the verdict: what a green check was allowed to do is part of what it means.
     lines.push("", `Settings — ${describeSettings(result)}`);
     for (const sev of CHECK_SEVERITIES) {
@@ -608,6 +672,12 @@ export function formatCheck(result) {
             lines.push(`- **${CHECK_RULES[i.rule].title}** \`${i.rule}\`: ${cell(i.evidence)}${i.embed ? ` _(in an embed of ${i.embed}: its behaviour, not the app's)_` : ""} — ${routeList(i.routes)}`);
         }
     }
+    if (result.worthALook.length > 0) {
+        lines.push("", `## Worth a look (${result.worthALook.length})`, "", "Measured exactly, and defects only under a convention of your project that the check cannot see. They are not counted above and never fail the gate, at any --fail-on.", "");
+        for (const o of result.worthALook) {
+            lines.push(`- **${WORTH_A_LOOK_RULES[o.rule].title}** \`${o.rule}\`: ${cell(o.evidence)} — a defect only if your project uses ${o.convention} — ${routeList(o.routes)}`);
+        }
+    }
     lines.push("", "## Routes", "", "| Route | Status | Controls | Issues |", "|---|---|---|---|");
     for (const r of result.routes) {
         const n = result.issues.filter((i) => i.routes.includes(r.path)).length;
@@ -701,5 +771,7 @@ export function toSummaryJson(result, toolVersion) {
         skippedFlows: result.skippedFlows,
         retest: result.retest,
         issues: result.issues,
+        // Apart from `issues` and `counts`, which the gate reads: none of these is counted or gated.
+        worthALook: result.worthALook,
     };
 }

package/dist/engine/design.js

@@ -274,6 +274,14 @@ function contrastFailures(records) {
     }
     return out;
 }
+/** The commonest off-grid values, smallest first and without their counts: "7px, 13px". */
+function gridValues(top) {
+    return top
+        .map(([v]) => v)
+        .sort((a, b) => a - b)
+        .map((v) => `${v}px`)
+        .join(", ");
+}
 /** Below the WCAG 2.2 target-size minimum; inline links are exempt by that rule. */
 function tooSmall(r) {
     return r.tag !== "a" && (r.rect.h < 24 || r.rect.w < 24) && r.rect.h > 0;
@@ -559,8 +567,8 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
         if (r.textLen > 40 && r.tag !== "a" && r.color !== "unknown")
             bodyColorFreq.set(r.color, (bodyColorFreq.get(r.color) ?? 0) + 1);
     const dominantBody = [...bodyColorFreq.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
+    const indistinct = dominantBody ? records.filter((r) => r.tag === "a" && r.textLen > 0 && !r.underline && r.color === dominantBody) : [];
     if (dominantBody) {
-        const indistinct = records.filter((r) => r.tag === "a" && r.textLen > 0 && !r.underline && r.color === dominantBody);
         if (indistinct.length > 0) {
             affordances.push(`→ ${indistinct.length} link(s) with no underline AND the same color as body text (e.g. ${label(indistinct[0])}) — invisible as links`);
         }
@@ -726,6 +734,12 @@ export function analyzeDesign(payload, viewport, chromeKeys = new Set()) {
         ...(page.scrollW > viewport.width + 8
             ? [{ rule: "horizontal-scroll", detail: `content ${page.scrollW}px wide in a ${viewport.width}px viewport` }]
             : []),
+        // The same thresholds as the SPACING and AFFORDANCES lines above, so the check and the audit agree on what they saw.
+        // Worded without counts or percentages: a spacing scale and a link style are app-wide conventions, so the same
+        // values on ten pages are one entry on ten routes, and the entry's fingerprint does not move when content does.
+        ...(pad.n > 10 && pad.pct > 20 ? [{ rule: "off-grid-spacing", detail: `paddings off a 4px grid: ${gridValues(pad.top)}` }] : []),
+        ...(mar.n > 10 && mar.pct > 20 ? [{ rule: "off-grid-spacing", detail: `vertical margins off a 4px grid: ${gridValues(mar.top)}` }] : []),
+        ...(indistinct.length > 0 ? [{ rule: "indistinct-link", detail: `links with no underline in the body-text colour ${dominantBody}` }] : []),
         ...chromeDefects,
     ];
     return { report, score, signatures, defects };

package/dist/engine/fingerprint.js

@@ -4,6 +4,17 @@ const HEX_RE = /^[0-9a-f]{12,}$/i;
 const NUM_RE = /^\d+$/;
 /** Query params that name a UI state (a different screen), not transient data. */
 const UI_STATE_PARAM_RE = /^(tab|view|mode|step|panel|section)$/i;
+/**
+ * Whether a path segment is an id that route identity collapses to `:id`: a
+ * UUID or long hex string anywhere, a number from the second real segment on.
+ * `index` counts as `path.split("/")` does, so the first real segment of a
+ * leading-slash path is 1 (see the note on numeric first segments below).
+ */
+export function isIdSegment(seg, index) {
+    if (UUID_RE.test(seg) || HEX_RE.test(seg))
+        return true;
+    return NUM_RE.test(seg) && index > 1;
+}
 /**
  * Normalize a URL into a route-class identity:
  * - path ids collapse (/orders/123 → /orders/:id)
@@ -38,13 +49,7 @@ export function normalizePath(rawUrl) {
     }
     // segments[0] is always "" for a leading-slash path, so the first REAL
     // segment is index 1 — that is the one a bare numeric page occupies.
-    const segments = path.split("/").map((seg, i) => {
-        if (UUID_RE.test(seg) || HEX_RE.test(seg))
-            return ":id";
-        if (NUM_RE.test(seg) && i > 1)
-            return ":id";
-        return seg;
-    });
+    const segments = path.split("/").map((seg, i) => (isIdSegment(seg, i) ? ":id" : seg));
     let normalized = segments.join("/") || "/";
     if (normalized === "")
         normalized = "/";
@@ -98,3 +103,60 @@ export function fingerprintState(url, elements) {
 export function shortHash(input) {
     return createHash("sha1").update(input).digest("hex").slice(0, 10);
 }
+/**
+ * A route as a lane wrote it, with every query string and every fragment that
+ * is not a hash route removed. A lane copies routes out of the address bar, and
+ * an address can carry `?access_token=`, `?code=`, `?session_id=` or a signed
+ * URL's `X-Amz-Signature=`; none of it identifies the page, and none of it may
+ * be stored or archived. A hash route (`#/things`) keeps its path, not its query.
+ * A `name=value` pair whose name reads as a credential is removed wherever it is.
+ */
+export function stripRouteQuery(route) {
+    return route
+        .replace(/\?[^\s()[\]]*/g, "")
+        .replace(/#(?!\/)[^\s()[\]]*/g, "")
+        .replace(/[\w-]*(token|signature|secret|password|session|code|key|auth|credential)[\w-]*=[^\s()[\]]*/gi, "")
+        .trim();
+}
+/** Page files a lane may name without a leading slash ("orders.html"). */
+const BARE_PAGE_RE = /^[\w-]+(\/[\w.-]+)*\.(html?|php|aspx?|jsp)$/i;
+/** A host with a port, or a loopback or IPv4 host, written without a scheme ("127.0.0.1:4173/orders.html"). */
+const BARE_HOST_RE = /^(?:[\w.-]+:\d+|localhost|\d{1,3}(?:\.\d{1,3}){3})(\/.*)?$/i;
+/**
+ * Every path one route from a lane report names, in the form a benchmark key
+ * entry's `route` is written in; empty when it names none.
+ *
+ * A lane writes its routes as free text — "/order.html?id=1042 (from
+ * /orders.html link)", "Orders (/orders.html)", "orders.html",
+ * "127.0.0.1:4173/orders.html", "/reports.html and /reports-scheduled.html".
+ * EVERY path in it counts, including one in a note: the benchmark uses these
+ * to set aside a verdict as another lane's, so a page left out makes a wrong
+ * verdict disappear, while a page taken in only keeps a verdict scored. A bare
+ * origin is "/", a bare page file gains its slash, the query goes, ids
+ * collapse as the engine's route identity collapses them, and "/index.html" is
+ * "/".
+ */
+export function laneRoutePaths(raw) {
+    const out = new Set();
+    for (const word of raw.split(/[\s,;|+()[\]]+|→|->|=>/)) {
+        const token = word.replace(/^[<"'`]+|[>"'`.:!]+$/g, "");
+        if (!token)
+            continue;
+        let path;
+        const url = /^https?:\/\/[^/\s]+(\/.*)?$/i.exec(token) ?? BARE_HOST_RE.exec(token);
+        if (url)
+            path = url[1] || "/";
+        else if (token.startsWith("/") || token.startsWith("#/"))
+            path = token;
+        else if (BARE_PAGE_RE.test(token.split(/[?#]/)[0]))
+            path = `/${token}`;
+        if (path === undefined)
+            continue;
+        let p = normalizePath(path).split("?")[0];
+        p = p.replace(/\/index\.html?$/i, "/");
+        if (p.length > 1)
+            p = p.replace(/\/+$/, "");
+        out.add(p || "/");
+    }
+    return [...out];
+}

package/dist/engine/lane.js

@@ -23,6 +23,7 @@
  * Pure logic, no browser, so every rule here is table-tested.
  */
 import { z } from "zod";
+import { isIdSegment } from "./fingerprint.js";
 import { FINDING_CATEGORIES } from "./memory.js";
 /** Upper bound on the decisions and routes arrays, so a report is always small enough to hold whole. */
 export const LANE_MAX_ITEMS = 255;
@@ -32,6 +33,8 @@ export const LANE_EVIDENCE_MAX = 160;
 export const LANE_OBSERVATION_MAX = 64;
 /** One line saying what blocked the lane; the detail belongs in a finding. */
 export const LANE_BLOCKED_BY_MAX = 200;
+/** One line naming the convention that would decide a "worth_a_look": "a 4px spacing scale", not an essay. */
+export const LANE_CONVENTION_MAX = 160;
 /** The planner chooses the lane name, so this cap is on the planner's side; it is stated all the same. */
 export const LANE_NAME_MAX = 40;
 /** A route as the lane saw it, query string included. */
@@ -39,7 +42,16 @@ export const LANE_ROUTE_MAX = 200;
 export const LANE_SEVERITIES = ["high", "medium", "low"];
 /** The same set scout_finding accepts, so a lane can report every finding it filed. */
 export const LANE_CATEGORIES = FINDING_CATEGORIES;
-export const LANE_VERDICTS = ["defect", "not_a_defect", "unsure"];
+/**
+ * "worth_a_look" is the third answer beside defect and not a defect: the
+ * observation is real, and whether it is a defect depends on a convention of
+ * the project that the run cannot see (a spacing scale, how navigation links
+ * are styled, whether controls carry test ids, whether the app ships to touch
+ * screens). SceneScout is used against any app, so it does not decide those;
+ * it names the convention and leaves the call to the project. It is not "I
+ * could not tell", which stays "unsure".
+ */
+export const LANE_VERDICTS = ["defect", "not_a_defect", "unsure", "worth_a_look"];
 export const LANE_STATUSES = ["complete", "partial", "blocked"];
 const Confidence = z.number().min(0).max(1);
 /**
@@ -57,12 +69,33 @@ export const LaneDecision = z
     confidence: Confidence,
     /** The same machine signature scout_finding takes as its cross-run dedup key. */
     evidence: z.string().min(1).max(LANE_EVIDENCE_MAX).nullable(),
+    /**
+     * The project convention that would make a "worth_a_look" a defect.
+     * Optional so a reply written before the verdict existed still parses;
+     * required (non-null) on a worth_a_look. On any other verdict the parser
+     * drops it and the fold says so: refusing a whole report over a field
+     * nothing reads would cost a round trip for nothing.
+     */
+    // Any string here: its length is checked only on a worth_a_look (below), because on every other verdict it is ignored.
+    convention: z.string().nullable().optional(),
 })
     .strict()
     .superRefine((d, ctx) => {
     if (d.verdict === "defect" && (d.severity === null || d.category === null)) {
         ctx.addIssue({ code: z.ZodIssueCode.custom, message: "a defect needs a severity and a category" });
     }
+    if (d.verdict === "worth_a_look") {
+        if (d.convention === undefined || d.convention === null || d.convention.trim() === "") {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: "a worth_a_look must name the convention that would decide it", path: ["convention"] });
+        }
+        else if (d.convention.length > LANE_CONVENTION_MAX) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `a convention is at most ${LANE_CONVENTION_MAX} characters`,
+                path: ["convention"],
+            });
+        }
+    }
 });
 export const LaneReport = z
     .object({
@@ -149,7 +182,26 @@ export function parseLaneReport(text, expectedLane) {
     if (expectedLane !== undefined && result.data.lane !== expectedLane) {
         return { ok: false, reason: `the report names lane "${result.data.lane}", but this reply was asked of lane "${expectedLane}"` };
     }
-    return { ok: true, report: result.data, aroundIgnored, entitiesDecoded: decoded.count };
+    // A convention means something only on a worth_a_look; elsewhere it is dropped, so nothing stored carries it, and named in the fold.
+    const conventionsIgnored = [];
+    const decisions = result.data.decisions.map((d) => {
+        if (d.verdict === "worth_a_look" || d.convention === undefined || d.convention === null)
+            return d;
+        conventionsIgnored.push(d.verdict);
+        const { convention: _dropped, ...rest } = d;
+        return rest;
+    });
+    return { ok: true, report: { ...result.data, decisions }, aroundIgnored, entitiesDecoded: decoded.count, conventionsIgnored };
+}
+/** The line the fold adds for each verdict whose convention was dropped: "convention ignored on a defect verdict"; empty when none was. */
+export function ignoredConventionsNote(verdicts) {
+    if (verdicts.length === 0)
+        return "";
+    const counts = new Map();
+    for (const v of verdicts)
+        counts.set(v, (counts.get(v) ?? 0) + 1);
+    const parts = [...counts].map(([v, n]) => `convention ignored on ${n === 1 ? `${/^[aeiou]/.test(v) ? "an" : "a"} ${v} verdict` : `${n} ${v} verdicts`}`);
+    return `\n(${parts.join("; ")}: only a worth_a_look names a convention.)`;
 }
 /**
  * The HTML character references a relay adds when it escapes text: the five
@@ -245,8 +297,9 @@ export function laneReportInstruction(lane) {
 const LANE_RUBRIC = [
     "Reply with ONE JSON object and nothing else — no prose before or after it, no explanation, no headings. A fenced ```json block is fine; anything outside it is discarded unread, so put nothing there you want kept.",
     `Shape: {"lane":<your lane name>,"status":<${quoteAll(LANE_STATUSES)}>,"decisions":[…],"routes":[…],"blocked_by":<string or null>}.`,
-    `Each decision: {"observation":<a short id for what was observed, unique in the report, at most ${LANE_OBSERVATION_MAX} characters>,"verdict":<${quoteAll(LANE_VERDICTS)}>,"severity":<${quoteAll(LANE_SEVERITIES)} or null>,"category":<${quoteAll(LANE_CATEGORIES)} or null>,"confidence":<0..1>,"evidence":<machine signature such as "GET /api/things 500", or null>}.`,
+    `Each decision: {"observation":<a short id for what was observed, unique in the report, at most ${LANE_OBSERVATION_MAX} characters>,"verdict":<${quoteAll(LANE_VERDICTS)}>,"severity":<${quoteAll(LANE_SEVERITIES)} or null>,"category":<${quoteAll(LANE_CATEGORIES)} or null>,"confidence":<0..1>,"evidence":<machine signature such as "GET /api/things 500", or null>,"convention":<string or null>}.`,
     `A "defect" must carry a severity and a category. "evidence" is a signature, not a sentence: at most ${LANE_EVIDENCE_MAX} characters. "confidence" is how sure you are of the verdict, calibrated: 0.5 means a coin flip, 0.95 means you would bet on it.`,
+    `"worth_a_look" is for an observation that is real but is a defect only under a convention of the project you cannot see (a spacing scale, how navigation links are styled, whether controls carry test ids, whether the app targets touch screens): it must name that convention in "convention", one line of at most ${LANE_CONVENTION_MAX} characters, such as "a 4px spacing scale". On every other verdict leave "convention" null or out: it is ignored there. It is not for "I could not tell": that is "unsure".`,
     `"routes" lists the routes you covered, each at most ${LANE_ROUTE_MAX} characters. "blocked_by" is one line of at most ${LANE_BLOCKED_BY_MAX} characters saying what stopped you: required when the status is "blocked", allowed with "partial", null with "complete"; the detail belongs in a finding. The lane name is at most ${LANE_NAME_MAX} characters. At most ${LANE_MAX_ITEMS} decisions and ${LANE_MAX_ITEMS} routes. Unknown keys are refused.`,
     "The object IS your final report: whatever hands it back must hand back the object verbatim, not a summary of it.",
 ];
@@ -258,12 +311,14 @@ export function summarizeLaneReport(r) {
     const defects = r.decisions.filter((d) => d.verdict === "defect");
     const high = defects.filter((d) => d.severity === "high").length;
     const unsure = r.decisions.filter((d) => d.verdict === "unsure").length;
+    const worthALook = r.decisions.filter((d) => d.verdict === "worth_a_look").length;
     const mean = r.decisions.length ? r.decisions.reduce((s, d) => s + d.confidence, 0) / r.decisions.length : 0;
     const parts = [
         r.status,
         `${r.decisions.length} judged`,
         `${defects.length} defects (${high} high)`,
         `${unsure} unsure`,
+        ...(worthALook > 0 ? [`${worthALook} worth a look`] : []),
         `mean confidence ${mean.toFixed(2)}`,
         `${r.routes.length} routes`,
     ];
@@ -271,6 +326,86 @@ export function summarizeLaneReport(r) {
         parts.push(`blocked by ${r.blocked_by}`);
     return `${r.lane}: ${parts.join(", ")}`;
 }
+/**
+ * Method, optional origin, path (template characters included), optional query
+ * and fragment, then a status only when it comes next: after an arrow or a
+ * colon, or after spaces, and nothing else. A status further along
+ * ("... (expected 403)") is a different claim about the request and is not
+ * read as its status.
+ *
+ * The separator is two alternatives rather than `\s*(?:->|:)?\s*`: with the
+ * arrow optional, two adjacent `\s*` can split a run of spaces every way
+ * there is, and evidence ending in a long run of whitespace took quadratic
+ * time to reject.
+ */
+const STATED_REQUEST_RE = /\b(GET|POST|PUT|PATCH|DELETE)\s+(?:https?:\/\/[^/\s]+)?(\/[A-Za-z0-9/_.:{}$*~%-]*)(?:\?[^\s#]*)?(?:#\S*)?(?:(?:\s*(?:->|→|=>|:)\s*|\s+)([1-5]\d{2})\b)?/gi;
+/** The requests a piece of evidence names, in order. */
+export function statedRequests(text) {
+    const out = [];
+    for (const m of text.matchAll(STATED_REQUEST_RE)) {
+        const raw = m[2].replace(/[.:,]+$/, "");
+        const start = (m.index ?? 0) + m[0].indexOf(m[2]);
+        out.push({ method: m[1].toUpperCase(), segments: pathSegments(raw), status: m[3] ?? null, start, end: start + raw.length });
+    }
+    return out;
+}
+function pathSegments(path) {
+    const trimmed = path.replace(/\/+$/, "");
+    if (trimmed === "")
+        return [];
+    return trimmed
+        .slice(1)
+        .split("/")
+        .map((seg) => {
+        try {
+            return decodeURIComponent(seg).toLowerCase();
+        }
+        catch {
+            return seg.toLowerCase();
+        }
+    });
+}
+/**
+ * A path-template segment: `{name}`, `:name` or `*`. Whole segments only —
+ * `order-{id}` is a literal, and so is `**`, which some routers read as "any
+ * number of segments": a template here stands for exactly one.
+ */
+export function isTemplateSegment(seg) {
+    return seg === "*" || /^\{[^/{}]+\}$/.test(seg) || /^:[a-z_][a-z0-9_-]*$/i.test(seg);
+}
+/**
+ * Whether two paths name the same route. A template segment on either side
+ * stands for ONE segment that is an id by route identity's own rule
+ * (`isIdSegment`: a number after the first segment, a UUID, a long hex
+ * string), or for another template. Never for a word: `/users/{id}` is not
+ * `/users/me`, `/things/:id` is not `/things/export`, and a path of three stars does
+ * not stand for every three-segment path. Same number of segments, every literal
+ * equal (case-insensitive), so a template never absorbs a slash or an empty
+ * segment.
+ */
+export function templatedPathsMatch(a, b) {
+    if (a.length !== b.length)
+        return false;
+    // +1: segments start at the first real one; isIdSegment counts as split("/") does.
+    const standsFor = (seg, i) => isTemplateSegment(seg) || isIdSegment(seg, i + 1);
+    return a.every((x, i) => {
+        const y = b[i];
+        if (isTemplateSegment(x))
+            return standsFor(y, i);
+        if (isTemplateSegment(y))
+            return standsFor(x, i);
+        return x === y;
+    });
+}
+/**
+ * Whether two stated requests are the same call: same method, same route with
+ * a template read as an id (see templatedPathsMatch), and the same status — both stated and equal, or
+ * both unstated. A different status is a different outcome of the call, and
+ * pairing a 200 with a 403 would file one claim under its opposite.
+ */
+export function requestsPair(a, b) {
+    return a.method === b.method && a.status === b.status && templatedPathsMatch(a.segments, b.segments);
+}
 /**
  * Which sessions are lanes of a parallel run, and whether each one's report
  * has been folded, so a lane's session is not closed before its decisions