scenescout 3.10.0 → 3.11.1

package/dist/engine/flow.js

@@ -0,0 +1,398 @@
+/**
+ * Saved flows: the steps `scenescout check` replays, as data.
+ *
+ * A flow is a short script a person or an agent wrote down once because it
+ * matters that it keeps working: open a page, click a control, see a result.
+ * The check replays every flow in `.scenescout/flows/*.json` after its crawl,
+ * with no model, so a flow that passed yesterday and breaks today fails the
+ * gate naming the flow and the step (ADR 12).
+ *
+ * The steps are `scout_run_plan`'s steps, so a plan that worked in an
+ * exploratory run can be saved as it is, plus three assertions a plan has no
+ * need for: text is visible, the URL matches, a request answered with a status.
+ *
+ * Everything here is pure: the schema and its error messages, the target
+ * grammar, and the rules that decide whether a URL or a request matched. The
+ * browser half is BrowserEngine.replayFlow, which only acts and reports.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { beaconResourceType, BROWSER_ENGINES } from "../browsers.js";
+import { MEMORY_DIRNAME, SELF_IGNORE_KEEP } from "./memory.js";
+/** Most steps one flow may hold. A longer flow is several flows, and each would fail more usefully on its own. */
+export const MAX_FLOW_STEPS = 50;
+/** Most flows one check replays. */
+export const MAX_FLOWS = 50;
+/** How long a step waits for its target, text, URL or request before it counts as broken. */
+export const FLOW_STEP_TIMEOUT_MS = 5000;
+/**
+ * How long a flow waits after its last step for a write that step set off
+ * late (a save on a timer, a debounced autosave), before it counts as passed.
+ */
+export const FLOW_AFTER_LAST_STEP_MS = 750;
+/** Where a project keeps its flows, relative to the project directory. */
+export const FLOWS_SUBDIR = path.join(MEMORY_DIRNAME, SELF_IGNORE_KEEP);
+export const TARGET_HELP = 'testid=…, text=…, label=… or role=<role>[name="…"]';
+/**
+ * The ARIA roles a `role=` target may name (WAI-ARIA 1.2, as Playwright's
+ * getByRole accepts them). A misspelt role matches nothing, so a flow using
+ * one would only ever fail at replay; it is refused when the file is read.
+ */
+export const ARIA_ROLE_LIST = [
+    "alert",
+    "alertdialog",
+    "application",
+    "article",
+    "banner",
+    "blockquote",
+    "button",
+    "caption",
+    "cell",
+    "checkbox",
+    "code",
+    "columnheader",
+    "combobox",
+    "complementary",
+    "contentinfo",
+    "definition",
+    "deletion",
+    "dialog",
+    "directory",
+    "document",
+    "emphasis",
+    "feed",
+    "figure",
+    "form",
+    "generic",
+    "grid",
+    "gridcell",
+    "group",
+    "heading",
+    "img",
+    "insertion",
+    "link",
+    "list",
+    "listbox",
+    "listitem",
+    "log",
+    "main",
+    "marquee",
+    "math",
+    "meter",
+    "menu",
+    "menubar",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "navigation",
+    "none",
+    "note",
+    "option",
+    "paragraph",
+    "presentation",
+    "progressbar",
+    "radio",
+    "radiogroup",
+    "region",
+    "row",
+    "rowgroup",
+    "rowheader",
+    "scrollbar",
+    "search",
+    "searchbox",
+    "separator",
+    "slider",
+    "spinbutton",
+    "status",
+    "strong",
+    "subscript",
+    "superscript",
+    "switch",
+    "tab",
+    "table",
+    "tablist",
+    "tabpanel",
+    "term",
+    "textbox",
+    "time",
+    "timer",
+    "toolbar",
+    "tooltip",
+    "tree",
+    "treegrid",
+    "treeitem",
+];
+export const ARIA_ROLES = new Set(ARIA_ROLE_LIST);
+export const ARIA_ROLES_MATCH_PLAYWRIGHT = ARIA_ROLE_LIST;
+/** Parse a target string, or null when it is not one. */
+export function parseTarget(target) {
+    for (const by of ["testid", "text", "label"]) {
+        if (target.startsWith(`${by}=`)) {
+            const value = target.slice(by.length + 1);
+            return value ? { by, value } : null;
+        }
+    }
+    const role = /^role=([a-z]+)(?:\[name=(?:"([^"]*)"|'([^']*)'|([^\]"']*))\])?$/i.exec(target);
+    if (!role)
+        return null;
+    const name = role[2] ?? role[3] ?? role[4];
+    return name === undefined ? { by: "role", role: role[1].toLowerCase() } : { by: "role", role: role[1].toLowerCase(), name };
+}
+const REQUEST_RE = /^(GET|POST|PUT|PATCH|DELETE|HEAD) (\/\S*)$/;
+function isRegex(pattern) {
+    try {
+        new RegExp(pattern);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const target = z
+    .string()
+    .refine((t) => parseTarget(t) !== null, { message: `must be ${TARGET_HELP}` })
+    .superRefine((t, ctx) => {
+    const parsed = parseTarget(t);
+    if (parsed?.by === "role" && !ARIA_ROLES.has(parsed.role)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `names the role "${parsed.role}", which is not an ARIA role (e.g. button, link, textbox, checkbox, tab)`,
+        });
+    }
+});
+const STEP_SCHEMAS = [
+    z.object({ action: z.literal("navigate"), target: z.string().regex(/^\//, "must be a path on the app, starting with /") }).strict(),
+    z.object({ action: z.literal("click"), target }).strict(),
+    z.object({ action: z.literal("type"), target, value: z.string(), pressEnter: z.boolean().optional(), replace: z.boolean().optional() }).strict(),
+    z.object({ action: z.literal("select"), target, value: z.string() }).strict(),
+    z.object({ action: z.literal("press"), value: z.string().min(1, "names the key to press, e.g. Enter") }).strict(),
+    z.object({ action: z.literal("expect-text"), text: z.string().min(1, "is the text that must be visible") }).strict(),
+    z.object({ action: z.literal("expect-url"), pattern: z.string().min(1).refine(isRegex, { message: "is not a valid regular expression" }) }).strict(),
+    z
+        .object({
+        action: z.literal("expect-request"),
+        request: z.string().regex(REQUEST_RE, 'must be a method and a path, e.g. "GET /api/things"'),
+        status: z.union([z.number().int().min(100).max(599), z.string().regex(/^[1-5]xx$/, 'must be a status such as 200, or a class such as "2xx"')]),
+    })
+        .strict(),
+];
+const stepSchema = z.discriminatedUnion("action", [...STEP_SCHEMAS]);
+export const FLOW_ACTIONS = STEP_SCHEMAS.map((s) => s.shape.action.value);
+const flowSchema = z
+    .object({
+    name: z.string().min(1).max(100).optional(),
+    description: z.string().max(500).optional(),
+    steps: z.array(stepSchema).min(1, "needs at least one step").max(MAX_FLOW_STEPS, `holds at most ${MAX_FLOW_STEPS} steps`),
+})
+    .strict()
+    .superRefine((flow, ctx) => {
+    // A flow starts from a page it names, never from wherever the crawl left the browser.
+    if (flow.steps[0] && flow.steps[0].action !== "navigate") {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["steps", 0, "action"], message: 'must be "navigate": a flow starts from a page it names' });
+    }
+});
+/** `steps[2].target`, the way a person would look for it in the file. */
+function fieldPath(p) {
+    if (p.length === 0)
+        return "(the whole file)";
+    return p.map((part, i) => (typeof part === "number" ? `[${part}]` : i === 0 ? part : `.${part}`)).join("");
+}
+function issueMessage(issue) {
+    if (issue.code === "unrecognized_keys")
+        return `unknown field(s) ${issue.keys.map((k) => `"${k}"`).join(", ")}`;
+    if (issue.code === "invalid_union_discriminator")
+        return `must be one of ${FLOW_ACTIONS.join(", ")}`;
+    if (issue.code === "invalid_type" && issue.received === "undefined")
+        return "is required";
+    return issue.message;
+}
+/** Validate one flow file's text. Every mistake names the file and the field. */
+export function parseFlow(text, file) {
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (err) {
+        return { ok: false, error: `${file}: not valid JSON (${err instanceof Error ? err.message : String(err)})` };
+    }
+    const parsed = flowSchema.safeParse(json);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.slice(0, 5).map((i) => `${fieldPath(i.path)} ${issueMessage(i)}`);
+        const more = parsed.error.issues.length > 5 ? ` (and ${parsed.error.issues.length - 5} more)` : "";
+        return { ok: false, error: `${file}: ${issues.join("; ")}${more}` };
+    }
+    return { ok: true, flow: { name: parsed.data.name ?? file.replace(/\.json$/i, ""), file, steps: parsed.data.steps } };
+}
+/**
+ * Read every `*.json` in a flows directory, in name order. Throws on the first
+ * file that is not a valid flow: a flow that cannot be read would otherwise
+ * pass by never running. Everything else in the directory is returned as
+ * skipped with its reason, so nothing there is left out without saying so. A
+ * symbolic link is followed when it resolves to a file inside the directory,
+ * and skipped when it resolves anywhere else.
+ */
+export function loadFlows(dir) {
+    const realDir = fs.realpathSync(dir);
+    const files = [];
+    const skipped = [];
+    for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((x, y) => (x.name < y.name ? -1 : x.name > y.name ? 1 : 0))) {
+        if (e.isDirectory()) {
+            skipped.push({ file: e.name, reason: "a directory: flows are not read from subdirectories" });
+            continue;
+        }
+        if (!e.name.toLowerCase().endsWith(".json")) {
+            skipped.push({ file: e.name, reason: "not a .json file" });
+            continue;
+        }
+        if (e.isSymbolicLink()) {
+            let target;
+            try {
+                target = fs.realpathSync(path.join(dir, e.name));
+            }
+            catch {
+                skipped.push({ file: e.name, reason: "a symbolic link to nothing" });
+                continue;
+            }
+            if (!target.startsWith(realDir + path.sep)) {
+                skipped.push({ file: e.name, reason: "a symbolic link to a file outside the flows directory" });
+                continue;
+            }
+            if (!fs.statSync(target).isFile()) {
+                skipped.push({ file: e.name, reason: "a symbolic link to something that is not a file" });
+                continue;
+            }
+        }
+        else if (!e.isFile()) {
+            skipped.push({ file: e.name, reason: "not a regular file" });
+            continue;
+        }
+        files.push(e.name);
+    }
+    if (files.length > MAX_FLOWS)
+        throw new Error(`${dir} holds ${files.length} flows; a check replays at most ${MAX_FLOWS}`);
+    const flows = files.map((file) => {
+        const parsed = parseFlow(fs.readFileSync(path.join(dir, file), "utf8"), file);
+        if (!parsed.ok)
+            throw new Error(`flow ${parsed.error}`);
+        return parsed.flow;
+    });
+    return { flows, skipped };
+}
+/**
+ * Which flows directory a check uses: the one named, none for "off", and
+ * otherwise the project's own when it exists. A directory that was named and
+ * is missing is an error, never a quiet check with no flows.
+ */
+export function resolveFlowsDir(flag, projectDir, exists) {
+    if (flag === "off")
+        return { dir: null };
+    if (flag !== undefined)
+        return exists(flag) ? { dir: flag } : { error: `--flows: no directory at ${flag}` };
+    const own = path.join(projectDir, FLOWS_SUBDIR);
+    return { dir: exists(own) ? own : null };
+}
+/** A step as the report names it. */
+export function describeStep(step) {
+    switch (step.action) {
+        case "navigate":
+        case "click":
+        case "select":
+            return `${step.action} ${step.target}`;
+        case "type":
+            return `type into ${step.target}${step.pressEnter ? " and press Enter" : ""}`;
+        case "press":
+            return `press ${step.value}`;
+        case "expect-text":
+            return `expect text ${JSON.stringify(step.text)}`;
+        case "expect-url":
+            return `expect the URL to match /${step.pattern}/`;
+        case "expect-request":
+            return `expect ${step.request} → ${step.status}`;
+    }
+}
+/** Whether a step acts on the page (and so opens a new window for expect-request) rather than reading it. */
+export function isAction(step) {
+    return !step.action.startsWith("expect-");
+}
+/** Path, query and hash: what an expect-url pattern is tested against, so the same flow passes on a laptop and a preview deployment. */
+export function urlMatches(pattern, url) {
+    let tail;
+    try {
+        const u = new URL(url);
+        tail = `${u.pathname}${u.search}${u.hash}`;
+    }
+    catch {
+        tail = url;
+    }
+    return new RegExp(pattern).test(tail);
+}
+/** A path pattern against a request's path: equal segment for segment, where `*` stands for any one segment. A trailing slash is ignored. */
+export function requestPathMatches(pattern, pathname) {
+    const split = (p) => p.replace(/\/+$/, "").split("/");
+    const want = split(pattern);
+    const got = split(pathname);
+    return want.length === got.length && want.every((seg, i) => seg === "*" || seg === got[i]);
+}
+export function statusMatches(expected, status) {
+    return typeof expected === "number" ? status === expected : String(status)[0] === expected[0];
+}
+/**
+ * Whether the requests seen since the last action include the one a step
+ * expects. The reason says what was seen instead, which is what a person
+ * fixing it needs: the right request with the wrong status, or none at all.
+ */
+export function matchRequest(expect, seen) {
+    const [, method, pattern] = REQUEST_RE.exec(expect.request) ?? [];
+    const same = seen.filter((r) => {
+        if (r.method.toUpperCase() !== method)
+            return false;
+        try {
+            return requestPathMatches(pattern, new URL(r.url).pathname);
+        }
+        catch {
+            return false;
+        }
+    });
+    if (same.some((r) => statusMatches(expect.status, r.status)))
+        return { ok: true };
+    if (same.length > 0) {
+        const statuses = [...new Set(same.map((r) => r.status))].join(", ");
+        return { ok: false, reason: `${expect.request} answered ${statuses}, expected ${expect.status}` };
+    }
+    return { ok: false, reason: `no ${expect.request} request was sent since the last action` };
+}
+/**
+ * The request kinds a refused write may be excused from a step for: what
+ * navigator.sendBeacon and <a ping> send, under every engine's name for it
+ * (browsers.ts `beaconResourceType`). They are fire-and-forget by design, a
+ * page sends them on its own schedule, and no step waits for one.
+ */
+export const BACKGROUND_REQUEST_TYPES = new Set(["ping", ...BROWSER_ENGINES.map(beaconResourceType)]);
+/**
+ * Split what the write policy refused during a step into what the step is
+ * charged with and background requests, which are only listed. The rule is
+ * the request's kind, never its origin: an app's API is often on another port
+ * or subdomain, and deciding by origin either hid a step's own write or
+ * blamed one on the app. So a fetch, an XHR or a form post is charged to the
+ * step wherever it goes, telemetry sent with fetch included; only a beacon or
+ * a ping is excused. A refusal with no kind recorded is charged. The app's
+ * origin is dropped from what is charged, for a shorter reason.
+ */
+export function splitRefusals(refusals, appOrigin) {
+    const charged = [];
+    const background = [];
+    for (const { sig, type } of refusals) {
+        if (type !== undefined && BACKGROUND_REQUEST_TYPES.has(type))
+            background.push(sig);
+        else
+            charged.push(sig.split(appOrigin).join(""));
+    }
+    return { charged, background };
+}
+/** The step a run stopped at, as the evidence of its issue or the reason the check could not run. */
+export function flowStepEvidence(run) {
+    if (run.outcome.status === "passed")
+        return "";
+    return `flow "${run.name}" (${run.file}) step ${run.outcome.step} of ${run.steps}, ${run.outcome.did}: ${run.outcome.reason}`;
+}

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;
@@ -271,6 +272,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

package/dist/engine/memory.js

@@ -451,6 +451,14 @@ export function requestsDisagree(a, b) {
  * refused save is data-loss to one and data-inconsistency to another. Across
  * families — a layout defect and a data defect — a shared quoted string names
  * a place on the page, not a bug.
+ *
+ * The presentation kinds are each a family of their own. They are not
+ * alternative labels for one observation: one element is routinely wrong in
+ * several independent ways at once — clipped out of view (visual), styled like
+ * body text (ux-polish), unnamed to a screen reader (a11y), missing its test id
+ * — and the findings about it quote the same control name and name the same
+ * test id. As one family, a link "styled like body text" was merged into the
+ * finding that the same link was clipped, and the second finding was lost.
  */
 const CATEGORY_FAMILY = {
     "data-inconsistency": "data",
@@ -460,10 +468,10 @@ const CATEGORY_FAMILY = {
     network: "failure",
     "console-error": "failure",
     "page-error": "failure",
-    visual: "presentation",
-    "ux-polish": "presentation",
-    a11y: "presentation",
-    "missing-testid": "presentation",
+    visual: "visual",
+    "ux-polish": "ux-polish",
+    a11y: "a11y",
+    "missing-testid": "missing-testid",
     "ux-confusing": "flow",
     "dead-end": "flow",
     security: "security",
@@ -485,7 +493,30 @@ export function sameFamily(a, b) {
     const fa = CATEGORY_FAMILY[a];
     return fa !== undefined && fa === CATEGORY_FAMILY[b];
 }
+/**
+ * Whether two findings may be one defect by KIND — what is wrong, as opposed
+ * to where. The same category, or two categories of one family. Every
+ * route-scoped rule below asks this first: evidence, a quoted literal and a
+ * title all say where a defect is as often as what it is, so none of them may
+ * merge a finding of one kind into a finding of another.
+ */
+function sameKind(a, b) {
+    return (!!a && a === b) || sameFamily(a, b);
+}
+/**
+ * The categories a finding of `category` can merge with, in list order —
+ * so scout_finding can tell a lane whose filing was merged which kinds would
+ * have been kept apart. An unknown category merges only with itself.
+ */
+export function mergeableCategories(category) {
+    const known = FINDING_CATEGORIES.filter((c) => sameKind(category, c));
+    return known.length > 0 ? known : [category];
+}
 function sameFinding(a, b) {
+    // What is wrong before where: two kinds of defect are two findings, however
+    // alike their evidence, quoted text or titles.
+    if (!sameKind(a.category, b.category))
+        return false;
     const aEv = a.evidence?.toLowerCase().replace(/\s+/g, " ").trim();
     const bEv = b.evidence?.toLowerCase().replace(/\s+/g, " ").trim();
     if (aEv && bEv && aEv === bEv)
@@ -506,7 +537,9 @@ function sameFinding(a, b) {
     // literal with the data defect describing what the button does — in its
     // detail or its own title. Merged, the layout defect was filed and then lost
     // from the report on most runs of a benchmark. Within a family, one bug
-    // filed twice under neighbouring categories still merges.
+    // filed twice under neighbouring categories still merges. Stricter than the
+    // kind check above in one way: an unknown category read from an older file
+    // is never merged on a quoted string, even with itself.
     //
     // And never when both findings' evidence names requests with no endpoint in
     // common. A quoted control name bridges two findings about that control
@@ -541,6 +574,8 @@ function sameFinding(a, b) {
 }
 /** 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). */
+export const SELF_IGNORE_KEEP = "flows";
 /** What the directory was called before the tool was renamed. */
 export const LEGACY_MEMORY_DIRNAME = ".scenecraft";
 /**
@@ -611,6 +646,10 @@ function liveOwnerPid(dir, isAlive) {
  * `git status`. That gets the same result without editing a file we do not
  * own, and it disappears cleanly when someone deletes the directory.
  *
+ * The one exception is `flows/`: saved flows are inputs a team commits so
+ * CI replays them, not output. A file written before that exception existed
+ * is still left alone; docs/ci.md says which two lines to add to it.
+ *
  * Best-effort and idempotent — a read-only checkout must never break attach,
  * and an existing file is left exactly as the user left it.
  */
@@ -621,7 +660,10 @@ export function writeSelfIgnore(dir) {
             return null;
         fs.writeFileSync(ignorePath, "# SceneScout exploratory-test artifacts: memory, session logs, status, report.\n" +
             "# Self-ignoring so a `git add -A` in the tested project can never commit them.\n" +
-            "*\n");
+            "*\n" +
+            "# Except the flows `scenescout check` replays: they are written to be committed.\n" +
+            `!${SELF_IGNORE_KEEP}/\n` +
+            `!${SELF_IGNORE_KEEP}/*.json\n`);
         return `Wrote ${MEMORY_DIRNAME}/.gitignore so these test artifacts stay out of your commits.`;
     }
     catch {