scenescout 3.11.1 → 3.13.0

package/dist/engine/dedup.js

@@ -0,0 +1,237 @@
+/**
+ * Measuring the finding-dedup decision against the answer keys, and an
+ * optional model-backed judge to measure beside it.
+ *
+ * The store's dedup rule (memory.ts, isDuplicateFinding) decides whether a
+ * newly filed finding is one it already records. Its mistakes are costly both
+ * ways: a wrong merge loses a finding, a missed merge shows one bug twice. This
+ * file turns the archived benchmark runs into labelled pairs — two findings on
+ * one page, "same" when the key classifies both to one entry and "different"
+ * when it classifies them to two — and scores any decider on them with
+ * accuracy, Brier and ECE.
+ *
+ * The model judge asks for a verdict (same / different / unsure) and a
+ * probability through one tool call, so its answer is structured, not parsed
+ * from prose. It is measured here and not used by the store: the rule stays
+ * the only thing that dedups until the judge's Brier beats it on these pairs.
+ * Everything here is pure; the network is the caller's, through `ask`.
+ */
+import { createHash } from "node:crypto";
+import { archiveApp, classify, findingText } from "./bench.js";
+import { MIN_FOR_A_VERDICT } from "./calibration.js";
+import { findingId, isDuplicateFinding } from "./memory.js";
+const pagesOf = (e) => [e.route, ...(e.alsoOn ?? [])];
+const norm = (s) => (s ?? "").toLowerCase().replace(/\s+/g, " ").trim();
+/**
+ * Every pair of findings, within one app across all its archived runs, whose
+ * key entries share a page, labelled by the key. Across runs because that is
+ * where the store dedups: a finding filed by one run against one an earlier
+ * run left. Findings with identical category, title and evidence are collapsed
+ * first, so a phrasing repeated in many runs is one finding, not a crowd of
+ * trivially-same pairs.
+ *
+ * The labels come from the key's patterns, so they are only as good as the
+ * key: a finding the key misclassifies gives a wrong label.
+ */
+export function buildPairs(archives, keys) {
+    const out = { pairs: [], findings: 0, identicalText: 0, unmatched: 0, ambiguous: 0, nonDefect: 0, archivesWithoutKey: 0 };
+    const byApp = new Map();
+    const seen = new Set();
+    for (const archive of archives) {
+        const app = archiveApp(archive);
+        const key = keys[app];
+        if (!key) {
+            out.archivesWithoutKey += 1;
+            continue;
+        }
+        const list = byApp.get(app) ?? [];
+        byApp.set(app, list);
+        for (const f of archive.findings) {
+            const text = `${app}|${norm(f.category)}|${norm(f.title)}|${norm(f.evidence)}`;
+            if (seen.has(text)) {
+                out.identicalText += 1;
+                continue;
+            }
+            seen.add(text);
+            const c = classify(findingText(f), key);
+            if (c === null)
+                out.unmatched += 1;
+            else if (c.kind === "ambiguous")
+                out.ambiguous += 1;
+            else if (c.kind === "nonDefect")
+                out.nonDefect += 1;
+            else {
+                out.findings += 1;
+                list.push({ f: { title: f.title, category: f.category ?? "", evidence: f.evidence, keyId: c.entry.id, run: archive.run }, pages: pagesOf(c.entry) });
+            }
+        }
+    }
+    for (const [app, list] of byApp) {
+        for (let i = 0; i < list.length; i++) {
+            for (let j = i + 1; j < list.length; j++) {
+                const route = list[i].pages.find((p) => list[j].pages.includes(p));
+                if (route === undefined)
+                    continue;
+                out.pairs.push({ app, route, a: list[i].f, b: list[j].f, same: list[i].f.keyId === list[j].f.keyId });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * At most `cap` pairs, chosen by a hash of their texts: the same pairs every
+ * time for the same archives, whatever order they were built in, and no
+ * preference for the runs that happen to be listed first.
+ */
+export function samplePairs(pairs, cap) {
+    if (!Number.isInteger(cap) || cap < 1)
+        throw new Error(`The pair cap must be a positive whole number, not ${cap}.`);
+    const h = (p) => createHash("sha256")
+        .update([p.app, p.route, p.a.run, p.a.title, p.a.evidence ?? "", p.b.run, p.b.title, p.b.evidence ?? ""].join("\n"))
+        .digest("hex");
+    return pairs
+        .map((p) => ({ p, k: h(p) }))
+        .sort((x, y) => (x.k < y.k ? -1 : x.k > y.k ? 1 : 0))
+        .slice(0, cap)
+        .map((x) => x.p);
+}
+const asStored = (f, route) => ({ title: f.title, category: f.category, evidence: f.evidence, detail: "", state: route });
+/**
+ * The store's own rule on a pair, as a judgement: the earlier finding is the
+ * stored one, the later the one being filed. It states no probability, so its
+ * probability is its verdict, 1 or 0.
+ */
+export function ruleJudgement(p) {
+    const existing = { ...asStored(p.a, p.route), id: findingId(asStored(p.a, p.route)) };
+    const same = isDuplicateFinding(existing, asStored(p.b, p.route));
+    return { verdict: same ? "same" : "different", pSame: same ? 1 : 0 };
+}
+// ── the model judge ─────────────────────────────────────────────────────────
+export const JUDGE_TOOL = {
+    name: "judge_pair",
+    description: "Record whether the two findings describe one defect.",
+    parameters: {
+        type: "object",
+        properties: {
+            verdict: { type: "string", enum: ["same", "different", "unsure"] },
+            p_same: { type: "number", minimum: 0, maximum: 1, description: "Probability the two findings are one defect." },
+        },
+        required: ["verdict", "p_same"],
+        additionalProperties: false,
+    },
+};
+export const JUDGE_SYSTEM = "You decide whether two findings filed by exploratory testers of one web app describe the SAME defect or DIFFERENT defects. " +
+    "Same: one root cause a single fix would close, however differently it is worded, categorised or evidenced. " +
+    "Different: two things a developer would fix separately, even on one page, one control or one endpoint. " +
+    "Answer only by calling judge_pair once, with no prose. verdict is same, different or unsure; p_same is your calibrated probability that they are one defect: " +
+    "about 0.5 when the text cannot tell, and near 0 or 1 only when it plainly can. Use unsure only when the findings give too little to go on.";
+/** What the judge is shown: the fields a tester filed, nothing from the key. */
+export function judgeKickoff(route, a, b) {
+    const show = (f) => ({ title: f.title, category: f.category, evidence: f.evidence ?? "" });
+    return `Both findings were filed on the page ${route}.\n\nFinding A: ${JSON.stringify(show(a))}\nFinding B: ${JSON.stringify(show(b))}`;
+}
+/**
+ * Read the judge's one tool call. Anything else — no call, another tool, a
+ * verdict outside the three, a probability outside 0–1 or one that
+ * contradicts its own verdict — is an error, never a guess at what was meant.
+ */
+export function parseJudgement(turn) {
+    const call = turn.calls.find((c) => c.name === JUDGE_TOOL.name);
+    if (!call)
+        return { ok: false, error: turn.note ?? `the model did not call ${JUDGE_TOOL.name}` };
+    if (call.argsError)
+        return { ok: false, error: call.argsError };
+    const input = call.input;
+    const verdict = input?.verdict;
+    const p = input?.p_same;
+    if (verdict !== "same" && verdict !== "different" && verdict !== "unsure")
+        return { ok: false, error: `the verdict ${JSON.stringify(verdict)} is not same, different or unsure` };
+    if (typeof p !== "number" || !Number.isFinite(p) || p < 0 || p > 1)
+        return { ok: false, error: `p_same ${JSON.stringify(p)} is not a probability` };
+    if ((verdict === "same" && p < 0.5) || (verdict === "different" && p > 0.5))
+        return { ok: false, error: `the verdict ${verdict} contradicts p_same ${p}` };
+    return { ok: true, judgement: { verdict, pSame: p } };
+}
+/**
+ * Decide one pair. With no judge the rule decides, as the store does. With a
+ * judge, the model decides when it answers same or different; when it fails
+ * for any reason, or is unsure, the rule decides and the note says why, so a
+ * run never silently becomes a run of the rule.
+ */
+export async function decideDuplicate(p, ask) {
+    const rule = () => ruleJudgement(p).verdict === "same";
+    if (!ask)
+        return { duplicate: rule(), by: "rule" };
+    let parsed;
+    try {
+        parsed = parseJudgement(await ask(JUDGE_SYSTEM, [JUDGE_TOOL], judgeKickoff(p.route, p.a, p.b)));
+    }
+    catch (err) {
+        parsed = { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+    if (!parsed.ok)
+        return { duplicate: rule(), by: "rule", note: `the model judge failed (${parsed.error}); the current rule decided` };
+    if (parsed.judgement.verdict === "unsure")
+        return { duplicate: rule(), by: "rule", judgement: parsed.judgement, note: "the model judge was unsure; the current rule decided" };
+    return { duplicate: parsed.judgement.verdict === "same", by: "model", judgement: parsed.judgement };
+}
+/**
+ * Accuracy, Brier and ECE of a decider over labelled pairs. `judgements[i]`
+ * answers `labels[i]`; null is a judge that gave no usable answer. The
+ * probability is scored against the key's label directly (a proper score for
+ * a yes/no question), not a confidence in the verdict: the two agree whenever
+ * the verdict follows the probability, which parseJudgement enforces.
+ */
+export function scorePairs(labels, judgements, bucketCount = 5) {
+    if (labels.length !== judgements.length)
+        throw new Error(`${labels.length} labels but ${judgements.length} judgements.`);
+    const out = { judged: 0, correct: 0, unsure: 0, failed: 0, sameInKey: 0, accuracy: null, brier: null, brierRef: null, buckets: [], ece: null };
+    const scored = [];
+    labels.forEach((same, i) => {
+        const j = judgements[i];
+        if (j === null)
+            return void (out.failed += 1);
+        if (j.verdict === "unsure")
+            return void (out.unsure += 1);
+        out.judged += 1;
+        if (same)
+            out.sameInKey += 1;
+        if ((j.verdict === "same") === same)
+            out.correct += 1;
+        scored.push({ p: j.pSame, y: same ? 1 : 0 });
+    });
+    if (out.judged < MIN_FOR_A_VERDICT)
+        return out;
+    const n = scored.length;
+    out.accuracy = out.correct / n;
+    out.brier = scored.reduce((s, x) => s + (x.p - x.y) ** 2, 0) / n;
+    const base = out.sameInKey / n;
+    out.brierRef = base * (1 - base);
+    // Equal-count buckets, cut only between different probabilities.
+    const sorted = [...scored].sort((x, y) => x.p - y.p);
+    const target = n / bucketCount;
+    let cur = [];
+    const flush = () => {
+        if (cur.length === 0)
+            return;
+        out.buckets.push({ n: cur.length, stated: cur.reduce((s, x) => s + x.p, 0) / cur.length, actual: cur.reduce((s, x) => s + x.y, 0) / cur.length });
+        cur = [];
+    };
+    sorted.forEach((x, i) => {
+        if (cur.length >= target && x.p !== sorted[i - 1].p)
+            flush();
+        cur.push(x);
+    });
+    flush();
+    out.ece = out.buckets.reduce((s, b) => s + (b.n / n) * Math.abs(b.stated - b.actual), 0);
+    return out;
+}
+/** One line per score, for the bench output and the results log. */
+export function formatPairScore(name, s) {
+    const head = `${name}: ${s.judged} judged (${s.sameInKey} same in the key), ${s.unsure} unsure, ${s.failed} failed`;
+    if (s.accuracy === null)
+        return `${head}; fewer than ${MIN_FOR_A_VERDICT} judged, no figures`;
+    const skill = s.brierRef ? ` (skill ${(1 - s.brier / s.brierRef).toFixed(2)} vs the base rate)` : "";
+    const buckets = s.buckets.map((b) => `n=${b.n} stated ${b.stated.toFixed(2)} actual ${b.actual.toFixed(2)}`).join("; ");
+    return `${head}; accuracy ${(s.accuracy * 100).toFixed(1)}%, Brier ${s.brier.toFixed(3)}${skill}, ECE ${s.ece.toFixed(3)} [${buckets}]`;
+}

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.
  *
@@ -572,6 +631,22 @@ function sameFinding(a, b) {
         return false;
     return findingJaccard(findingTokens(a.title), findingTokens(b.title)) >= 0.5;
 }
+/** A finding's stored id: its category, title and route, so the same finding filed twice hashes the same. */
+export function findingId(f) {
+    return shortHash(`${f.category}|${f.title.toLowerCase().trim()}|${f.state.split("#")[0]}`);
+}
+/**
+ * The dedup rule `addFinding` applies: whether `incoming` is the finding
+ * `existing` already records. The same id; or, on the same route, the same
+ * finding by evidence, a quoted literal or title overlap (sameFinding); or,
+ * from any route, the same endpoint failing the same way (sameEndpointBug).
+ * Exported so the benchmark scores the rule the store runs, not a copy of it.
+ */
+export function isDuplicateFinding(existing, incoming) {
+    return (existing.id === findingId(incoming) ||
+        (existing.state.split("#")[0] === incoming.state.split("#")[0] && sameFinding(existing, incoming)) ||
+        sameEndpointBug(existing, incoming));
+}
 /** Per-project directory for memory, session logs, and reports. */
 export const MEMORY_DIRNAME = ".scenescout";
 /** The one directory under it that is committed rather than ignored: saved flows (flow.ts). */
@@ -880,6 +955,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 +1200,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 +1490,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.
@@ -1401,14 +1503,19 @@ export class MemoryStore {
             url: redactSecrets(input.url),
             evidence: input.evidence ? redactSecrets(input.evidence) : input.evidence,
         };
-        const route = f.state.split("#")[0];
-        const id = shortHash(`${f.category}|${f.title.toLowerCase().trim()}|${route}`);
-        const existing = this.data.findings.find((x) => x.id === id || (x.state.split("#")[0] === route && sameFinding(x, f)) || sameEndpointBug(x, f));
+        const id = findingId(f);
+        const existing = this.data.findings.find((x) => isDuplicateFinding(x, f));
         if (existing) {
             existing.runs += 1;
             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 +1532,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 +1569,7 @@ export class MemoryStore {
         };
         this.data.findings.push(finding);
         this.flush();
-        return [finding, true];
+        return [finding, true, false];
     }
     get findings() {
         return this.data.findings;