@asrunjs/asrun 0.9.0 → 0.11.0

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

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

package/dist/lib/case-doc.js

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

package/dist/lib/explore-notes.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The local exploration note: what `/explore-case` saw on the page, in a form `/gen-spec` can read.
+ *
+ * It lives under `.explore/notes/<case-id>/<profile-id>.json`, one file per profile, so a run with `--profiles` never
+ * has to merge with an earlier one. `.explore/` is git-ignored local state: a note is optional, may be deleted at any
+ * time, and a fresh checkout simply has none (generation then replays the case as before).
+ *
+ * A note holds only what the case does not: locators the agent confirmed on the page, the data-call paths of the
+ * actions that load something, and the match count of a target card's element. Expected values stay in the case's
+ * `## Values`, ready signals in the case's `Ready when:` lines, and assertions nowhere near this file.
+ */
+export declare const NOTES_VERSION = 1;
+export interface ExploreLocator {
+    /** What the locator is for, in words ("the header navigation link"). */
+    purpose: string;
+    /** A Playwright locator as `browser_generate_locator` returned it, for example `page.getByRole('link', {name: 'Home'})`. */
+    locator: string;
+}
+export interface ExploreNoteStep {
+    /** The path the step runs on, relative to `baseURL` (for example `/documents/`). */
+    url?: string;
+    locators?: ExploreLocator[];
+    /** Data-call paths the step's action starts, path only (`/api/articles`). */
+    requests?: string[];
+}
+export interface ExploreNoteTarget {
+    locator: string;
+    /** How many elements the locator matched when it was confirmed (1 for a target that is not a question). */
+    matches?: number;
+}
+export interface ExploreNote {
+    version: typeof NOTES_VERSION;
+    caseId: string;
+    profile: string;
+    env?: string;
+    /** sha256 of `cases/<case-id>.md` when the note was written; a different one makes the note stale. */
+    caseSha256: string;
+    capturedAt: string;
+    /** Set when a later `/gen-spec` refreshed an entry it confirmed on the page. */
+    updatedAt?: string;
+    steps: Record<string, ExploreNoteStep>;
+    targets?: Record<string, ExploreNoteTarget>;
+}
+export interface ExploreNoteError {
+    file: string;
+    problems: string[];
+}
+/** The folder that holds one case's notes; `<case-id>` may contain its group folder (`documents/landing-page`). */
+export declare function exploreNotesDir(caseId: string): string;
+/** The note of one profile: `.explore/notes/<case-id>/<profile-id>.json`. */
+export declare function exploreNotesFile(caseId: string, profileId: string): string;
+/** sha256 of the case document, or null when it does not exist. */
+export declare function caseSha256(caseId: string): string | null;
+export type NoteFreshness = 'fresh' | 'stale' | 'no-case';
+/**
+ * Whether a note still describes the case. A stale note is not an error: `/gen-spec` replays the case and ignores it.
+ */
+export declare function noteFreshness(note: ExploreNote): {
+    state: NoteFreshness;
+    reason?: string;
+};
+/** Every reason the note is not usable, in plain words. An empty list means it is valid. */
+export declare function validateExploreNote(value: unknown, expected: {
+    caseId: string;
+    profile: string;
+}): string[];
+/**
+ * Reads every note of a case (or one profile's), parses and validates it. A malformed file is reported, never thrown:
+ * the caller decides whether it matters, and generation treats an unreadable note as a missing one.
+ */
+export declare function readExploreNotes(caseId: string, profileId?: string): {
+    notes: ExploreNote[];
+    errors: ExploreNoteError[];
+};

package/dist/lib/explore-notes.js

@@ -0,0 +1,242 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { isValidCaseId } from './case-id.js';
+import { CASES_DIR, EXPLORE_DIR } from './paths.js';
+/**
+ * The local exploration note: what `/explore-case` saw on the page, in a form `/gen-spec` can read.
+ *
+ * It lives under `.explore/notes/<case-id>/<profile-id>.json`, one file per profile, so a run with `--profiles` never
+ * has to merge with an earlier one. `.explore/` is git-ignored local state: a note is optional, may be deleted at any
+ * time, and a fresh checkout simply has none (generation then replays the case as before).
+ *
+ * A note holds only what the case does not: locators the agent confirmed on the page, the data-call paths of the
+ * actions that load something, and the match count of a target card's element. Expected values stay in the case's
+ * `## Values`, ready signals in the case's `Ready when:` lines, and assertions nowhere near this file.
+ */
+export const NOTES_VERSION = 1;
+const HASH = /^[a-f0-9]{64}$/;
+const PROFILE_FILE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const STEP_KEY = /^[1-9]\d*$/;
+const TARGET_KEY = /^T[1-9]\d*$/;
+// A request pattern is a path, never a URL with a host or a query string that could carry a token.
+const UNSAFE_REQUEST = /[?#]|:\/\//;
+const SECRET_PARAM = /(?:^|[/&])(?:token|cookie|password|authorization|secret|signature|sig|session)=/i;
+const MAX_LOCATOR = 400;
+const MAX_PURPOSE = 200;
+const MAX_REQUEST = 200;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isOneLine = (value) => !/[\r\n]/.test(value);
+/** The folder that holds one case's notes; `<case-id>` may contain its group folder (`documents/landing-page`). */
+export function exploreNotesDir(caseId) {
+    if (!isValidCaseId(caseId))
+        throw new Error(`"${caseId}" is not a valid case id`);
+    return path.join(EXPLORE_DIR, 'notes', ...caseId.split('/'));
+}
+/** The note of one profile: `.explore/notes/<case-id>/<profile-id>.json`. */
+export function exploreNotesFile(caseId, profileId) {
+    if (!PROFILE_FILE.test(profileId))
+        throw new Error(`"${profileId}" is not a valid profile id`);
+    return path.join(exploreNotesDir(caseId), `${profileId}.json`);
+}
+/** sha256 of the case document, or null when it does not exist. */
+export function caseSha256(caseId) {
+    if (!isValidCaseId(caseId))
+        return null;
+    try {
+        return crypto.createHash('sha256').update(fs.readFileSync(path.join(CASES_DIR, `${caseId}.md`))).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether a note still describes the case. A stale note is not an error: `/gen-spec` replays the case and ignores it.
+ */
+export function noteFreshness(note) {
+    const current = caseSha256(note.caseId);
+    if (current === null)
+        return { state: 'no-case', reason: 'the case file does not exist' };
+    if (current !== note.caseSha256)
+        return { state: 'stale', reason: 'the case file changed after the note was written' };
+    return { state: 'fresh' };
+}
+function checkLocator(value, where, problems) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        problems.push(`${where} must be a locator string`);
+        return;
+    }
+    if (!isOneLine(value))
+        problems.push(`${where} must be one line`);
+    if (value.length > MAX_LOCATOR)
+        problems.push(`${where} is longer than ${MAX_LOCATOR} characters`);
+    if (!value.startsWith('page.'))
+        problems.push(`${where} must start with "page." (use browser_generate_locator)`);
+    if (value.includes('=>'))
+        problems.push(`${where} must be a locator, not code`);
+}
+function checkRequest(value, where, problems) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        problems.push(`${where} must be a request path`);
+        return;
+    }
+    if (!isOneLine(value))
+        problems.push(`${where} must be one line`);
+    if (value.length > MAX_REQUEST)
+        problems.push(`${where} is longer than ${MAX_REQUEST} characters`);
+    if (!value.startsWith('/') || value.startsWith('//'))
+        problems.push(`${where} must start with "/" (a path, not a URL)`);
+    if (UNSAFE_REQUEST.test(value))
+        problems.push(`${where} must have no host, query string or fragment`);
+    if (SECRET_PARAM.test(value))
+        problems.push(`${where} must not carry a token, cookie or session`);
+}
+function checkPurpose(value, where, problems) {
+    if (typeof value !== 'string' || value.trim() === '')
+        problems.push(`${where} must be a short description`);
+    else if (!isOneLine(value))
+        problems.push(`${where} must be one line`);
+    else if (value.length > MAX_PURPOSE)
+        problems.push(`${where} is longer than ${MAX_PURPOSE} characters`);
+}
+function checkSteps(value, problems) {
+    if (!isRecord(value)) {
+        problems.push('steps must be an object keyed by step number');
+        return;
+    }
+    for (const [step, body] of Object.entries(value)) {
+        const where = `steps["${step}"]`;
+        if (!STEP_KEY.test(step))
+            problems.push(`${where}: the key must be a positive step number`);
+        if (!isRecord(body)) {
+            problems.push(`${where} must be an object`);
+            continue;
+        }
+        if (body.url !== undefined) {
+            const url = body.url;
+            if (typeof url !== 'string' || !url.startsWith('/'))
+                problems.push(`${where}.url must start with "/"`);
+            else if (UNSAFE_REQUEST.test(url))
+                problems.push(`${where}.url must have no host, query string or fragment`);
+        }
+        if (body.locators !== undefined) {
+            if (!Array.isArray(body.locators))
+                problems.push(`${where}.locators must be a list`);
+            else {
+                for (const [index, locator] of body.locators.entries()) {
+                    const item = `${where}.locators[${index}]`;
+                    if (!isRecord(locator)) {
+                        problems.push(`${item} must be an object with "purpose" and "locator"`);
+                        continue;
+                    }
+                    checkPurpose(locator.purpose, `${item}.purpose`, problems);
+                    checkLocator(locator.locator, `${item}.locator`, problems);
+                }
+            }
+        }
+        if (body.requests !== undefined) {
+            if (!Array.isArray(body.requests))
+                problems.push(`${where}.requests must be a list`);
+            else
+                body.requests.forEach((request, index) => checkRequest(request, `${where}.requests[${index}]`, problems));
+        }
+        const known = new Set(['url', 'locators', 'requests']);
+        for (const key of Object.keys(body))
+            if (!known.has(key))
+                problems.push(`${where}.${key} is not a known field`);
+    }
+}
+function checkTargets(value, problems) {
+    if (!isRecord(value)) {
+        problems.push('targets must be an object keyed by target id');
+        return;
+    }
+    for (const [id, target] of Object.entries(value)) {
+        const where = `targets["${id}"]`;
+        if (!TARGET_KEY.test(id))
+            problems.push(`${where}: the key must be a target id such as "T1"`);
+        if (!isRecord(target)) {
+            problems.push(`${where} must be an object`);
+            continue;
+        }
+        checkLocator(target.locator, `${where}.locator`, problems);
+        if (target.matches !== undefined && (!Number.isInteger(target.matches) || target.matches < 1)) {
+            problems.push(`${where}.matches must be a positive whole number`);
+        }
+        const known = new Set(['locator', 'matches']);
+        for (const key of Object.keys(target))
+            if (!known.has(key))
+                problems.push(`${where}.${key} is not a known field`);
+    }
+}
+/** Every reason the note is not usable, in plain words. An empty list means it is valid. */
+export function validateExploreNote(value, expected) {
+    const problems = [];
+    if (!isRecord(value))
+        return ['the note is not a JSON object'];
+    if (value.version !== NOTES_VERSION)
+        problems.push(`version must be ${NOTES_VERSION}`);
+    if (value.caseId !== expected.caseId)
+        problems.push(`caseId must be "${expected.caseId}"`);
+    if (value.profile !== expected.profile)
+        problems.push(`profile must be "${expected.profile}"`);
+    if (typeof value.profile !== 'string' || !PROFILE_FILE.test(value.profile)) {
+        problems.push('profile must be a profile id (letters, digits, ".", "_" and "-")');
+    }
+    if (typeof value.caseSha256 !== 'string' || !HASH.test(value.caseSha256)) {
+        problems.push('caseSha256 must be the sha256 of the case file (run "explore:notes <case-id> --hash")');
+    }
+    if (typeof value.capturedAt !== 'string' || value.capturedAt.trim() === '') {
+        problems.push('capturedAt must be an ISO date-time');
+    }
+    if (value.updatedAt !== undefined && typeof value.updatedAt !== 'string')
+        problems.push('updatedAt must be a string');
+    if (value.env !== undefined && (typeof value.env !== 'string' || value.env.trim() === '')) {
+        problems.push('env must be a non-empty string when it is present');
+    }
+    checkSteps(value.steps, problems);
+    if (value.targets !== undefined)
+        checkTargets(value.targets, problems);
+    const known = new Set(['version', 'caseId', 'profile', 'env', 'caseSha256', 'capturedAt', 'updatedAt', 'steps', 'targets']);
+    for (const key of Object.keys(value))
+        if (!known.has(key))
+            problems.push(`${key} is not a known field`);
+    return problems;
+}
+/**
+ * Reads every note of a case (or one profile's), parses and validates it. A malformed file is reported, never thrown:
+ * the caller decides whether it matters, and generation treats an unreadable note as a missing one.
+ */
+export function readExploreNotes(caseId, profileId) {
+    const errors = [];
+    const notes = [];
+    if (!isValidCaseId(caseId))
+        return { notes, errors: [{ file: caseId, problems: ['not a valid case id'] }] };
+    let files;
+    try {
+        files = fs.readdirSync(exploreNotesDir(caseId)).filter((file) => file.endsWith('.json'));
+    }
+    catch {
+        return { notes, errors };
+    }
+    for (const file of files.sort()) {
+        const profile = path.basename(file, '.json');
+        if (profileId !== undefined && profile !== profileId)
+            continue;
+        const full = path.join(exploreNotesDir(caseId), file);
+        let parsed;
+        try {
+            parsed = JSON.parse(fs.readFileSync(full, 'utf8'));
+        }
+        catch (error) {
+            errors.push({ file: full, problems: [`not valid JSON: ${error.message}`] });
+            continue;
+        }
+        const problems = validateExploreNote(parsed, { caseId, profile });
+        if (problems.length > 0)
+            errors.push({ file: full, problems });
+        else
+            notes.push(parsed);
+    }
+    return { notes, errors };
+}

package/dist/lib/paths.d.ts

@@ -25,6 +25,8 @@ export declare const CASES_DIR: string;
 export declare const TESTS_DIR: string;
 export declare const REPORTS_DIR: string;
 export declare const TMP_DIR: string;
+/** Local agent output (reference screenshots, exploration notes), git-ignored and safe to delete. */
+export declare const EXPLORE_DIR: string;
 export declare const TEMPLATES_DIR: string;
 export declare const SKILLS_DIR: string;
 /**

package/dist/lib/paths.js

@@ -82,6 +82,8 @@ export const CASES_DIR = path.join(ROOT, 'cases');
 export const TESTS_DIR = path.join(ROOT, 'tests');
 export const REPORTS_DIR = path.join(ROOT, 'reports');
 export const TMP_DIR = path.join(ROOT, '.tmp');
+/** Local agent output (reference screenshots, exploration notes), git-ignored and safe to delete. */
+export const EXPLORE_DIR = path.join(ROOT, '.explore');
 export const TEMPLATES_DIR = path.join(FRAMEWORK_ROOT, 'templates');
 export const SKILLS_DIR = path.join(FRAMEWORK_ROOT, '.claude', 'skills');
 /**