scenescout 3.11.1 → 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

@@ -103,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

@@ -33,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. */
@@ -40,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);
 /**
@@ -58,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({
@@ -150,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
@@ -246,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.",
 ];
@@ -259,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`,
     ];

package/dist/engine/memory.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { normalizePath, shortHash } from "./fingerprint.js";
+import { laneRoutePaths, normalizePath, shortHash, stripRouteQuery } from "./fingerprint.js";
 import { isFormBookkeeping } from "./forms.js";
 /**
  * The kinds a finding can be. One list: scout_finding's input schema, the lane
@@ -26,6 +26,32 @@ export const FINDING_CATEGORIES = [
     "missing-testid",
     "other",
 ];
+/**
+ * Whether a finding is in the "worth a look" tier. Anything else a file holds
+ * reads as a defect: a finding is never taken out of the defect count on a
+ * value this version does not know.
+ */
+export function isWorthALook(f) {
+    return f.tier === "worth_a_look";
+}
+/**
+ * The tier a finding keeps when it is found again. A defect wins: a finding
+ * someone filed as a defect is a decision about the project's convention, and
+ * a later "worth a look" for the same thing does not undo it. A worth-a-look
+ * filed again as a defect is promoted, and loses its convention. Two
+ * worth-a-looks keep the first convention unless it had none.
+ */
+/** Drops a finding's tier and convention in place, so a merged tier can be assigned onto it. */
+function withoutTier(f) {
+    delete f.tier;
+    delete f.convention;
+    return f;
+}
+export function mergeTier(existing, incoming) {
+    if (!isWorthALook(existing) || !isWorthALook(incoming))
+        return {};
+    return { tier: "worth_a_look", convention: existing.convention || incoming.convention };
+}
 /**
  * Most states a route may keep. A route accumulates one state per distinct
  * element set, so a register with filters, tabs and paging produces dozens;
@@ -213,12 +239,19 @@ export function mergeMemory(mine, theirs) {
         // the other side did not go on to re-find it as a regression.
         const newer = f.foundAt >= other.foundAt ? f : other;
         const older = newer === f ? other : f;
-        byId.set(f.id, {
+        const merged = {
             ...newer,
             runs: Math.max(f.runs, other.runs),
             evidence: newer.evidence ?? older.evidence,
             regressedAt: newer.regressedAt ?? older.regressedAt,
-        });
+        };
+        // The tier is not "later knowledge wins": a defect on either side is a decision
+        // about the convention, and a store still holding the worth-a-look must not undo it.
+        const tier = mergeTier(older, newer);
+        Object.assign(withoutTier(merged), tier);
+        if (!isWorthALook(merged) && isWorthALook(newer))
+            merged.severity = older.severity;
+        byId.set(f.id, merged);
     }
     out.findings = [...byId.values()];
     const unionRecord = (a, b) => (a || b ? { ...(b ?? {}), ...(a ?? {}) } : undefined);
@@ -264,8 +297,34 @@ export function mergeMemory(mine, theirs) {
     out.laneDecisions = [...byDecision.values()].sort((a, b) => a.at.localeCompare(b.at)).slice(-MAX_LANE_DECISIONS);
     if (out.laneDecisions.length === 0)
         delete out.laneDecisions;
+    // The same reason as decisions: each lane folds in its own process. A set
+    // union per lane, so merging the same document twice changes nothing.
+    out.laneRoutes = { ...(theirs.laneRoutes ?? {}) };
+    for (const [lane, routes] of Object.entries(mine.laneRoutes ?? {})) {
+        out.laneRoutes[lane] = unionRoutes(out.laneRoutes[lane] ?? [], routes);
+    }
+    if (Object.keys(out.laneRoutes).length === 0)
+        delete out.laneRoutes;
     return out;
 }
+/** Most routes kept per lane. A lane report carries at most a few hundred; this keeps a long-lived project's file small. */
+export const MAX_LANE_ROUTES = 255;
+/**
+ * `b` added to `a`. Two routes naming the same page(s) are one — the later
+ * wording wins — and past the cap the NEWEST are kept: a long-lived project
+ * reuses lane names, and what a lane covers now is what a new verdict is
+ * judged against.
+ */
+function unionRoutes(a, b) {
+    const byPage = new Map();
+    for (const r of [...a, ...b]) {
+        const paths = laneRoutePaths(r);
+        const id = paths.length ? paths.sort().join(" ") : `text:${r}`;
+        byPage.delete(id);
+        byPage.set(id, r);
+    }
+    return [...byPage.values()].slice(-MAX_LANE_ROUTES);
+}
 /**
  * What makes two stored decisions the same judgement.
  *
@@ -880,6 +939,11 @@ export class MemoryStore {
                     dupOf.evidence = f.evidence;
                 if (f.status === "resolved")
                     dupOf.status = "resolved";
+                const promoted = isWorthALook(dupOf) && !isWorthALook(f);
+                const tier = mergeTier(dupOf, f);
+                Object.assign(withoutTier(dupOf), tier);
+                if (promoted)
+                    dupOf.severity = f.severity;
                 merged += 1;
             }
             else {
@@ -1120,6 +1184,27 @@ export class MemoryStore {
         // every call after the first reported nothing kept — while storing fine.
         return Math.min(added, MAX_LANE_DECISIONS);
     }
+    /** The routes each lane's report said it covered. Empty on a project that has never run one. */
+    get laneRoutes() {
+        return this.data.laneRoutes ?? {};
+    }
+    /**
+     * Record the routes a lane's accepted report listed, added to any it listed
+     * before. Redacted like every other string a lane writes, with query
+     * strings and fragments removed. Returns how many were new.
+     */
+    addLaneRoutes(lane, routes) {
+        const before = this.data.laneRoutes?.[lane] ?? [];
+        // No query string or fragment is stored: a route is copied from the
+        // address bar, and an address can carry a token.
+        const after = unionRoutes(before, routes.map((r) => redactSecrets(stripRouteQuery(r))).filter((r) => r.length > 0));
+        const added = after.filter((r) => !before.includes(r)).length;
+        if (after.length === before.length && after.every((r, i) => r === before[i]))
+            return 0;
+        this.data.laneRoutes = { ...(this.data.laneRoutes ?? {}), [lane]: after };
+        this.flush();
+        return added;
+    }
     /** Mark a finding resolved; returns it or null. */
     resolveFinding(id) {
         const f = this.data.findings.find((x) => x.id === id);
@@ -1389,6 +1474,7 @@ export class MemoryStore {
      *    across sessions rarely reuses the exact words — Jaccard catches it).
      * Returns [finding, isNew].
      */
+    /** Returns the finding, whether it is new, and whether an existing worth-a-look was just promoted to a defect by it. */
     addFinding(input) {
         // Redact BEFORE the id is derived, so a re-found finding whose quoted
         // secret differs by a character still hashes to the same id.
@@ -1409,6 +1495,12 @@ export class MemoryStore {
             existing.foundAt = new Date().toISOString();
             if (!existing.evidence && f.evidence)
                 existing.evidence = f.evidence;
+            // A worth-a-look filed again as a defect is promoted, at the severity the defect was filed at.
+            const promoted = isWorthALook(existing) && !isWorthALook(f);
+            const tier = mergeTier(existing, f);
+            Object.assign(withoutTier(existing), tier);
+            if (promoted)
+                existing.severity = f.severity;
             // Re-finding a RESOLVED finding is a regression — reopen it loudly
             // rather than letting it hide in the report's completed section. But a
             // FUZZY match must never resurrect a fixed bug: telling someone a
@@ -1425,7 +1517,7 @@ export class MemoryStore {
                 existing.regressedAt = existing.foundAt;
             }
             this.flush();
-            return [existing, false];
+            return [existing, false, promoted];
         }
         // Repro trace scoped to the finding's route: everything since the action
         // that landed there, not 12 lines of unrelated cross-module noise.
@@ -1462,7 +1554,7 @@ export class MemoryStore {
         };
         this.data.findings.push(finding);
         this.flush();
-        return [finding, true];
+        return [finding, true, false];
     }
     get findings() {
         return this.data.findings;