@jevitate/cli 0.8.0 → 0.10.0

package/dist/change-context.js

@@ -0,0 +1,203 @@
+/**
+ * #453 change-aware self-heal: read a git range read-only and build a `ChangeScope`.
+ * The only IO is `git rev-parse` / `git merge-base` / `git diff`, always via an argv array, never a
+ * shell, and only resolved 40-hex SHAs ever reach `diff`. Raw diff text leaves only as `ChangeEvidence`.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { extractChangeEvidence, isSkippedChangePath } from "@jevitate/runtime";
+const execFileAsync = promisify(execFile);
+const GIT_MAX_BUFFER = 8 * 1024 * 1024;
+const DEFAULT_MAX_FILES = 400;
+const DEFAULT_MAX_BYTES = 4_000_000;
+const MAX_NOTES = 20;
+const MAX_NOTE_LENGTH = 2000;
+const SHA_RE = /^[0-9a-f]{40}$/;
+// The whole range must be ref-safe characters; the separator, if any, is exactly `..` or `...`.
+const RANGE_RE = /^([A-Za-z0-9._\/~^@{}-]{1,200})(?:(\.\.\.?)([A-Za-z0-9._\/~^@{}-]{1,200}))?$/;
+/** The caller supplied a syntactically invalid range or note set. */
+export class ChangesArgsError extends Error {
+    code = "E_CHANGES_ARGS";
+    constructor(message) {
+        super(message);
+        this.name = "ChangesArgsError";
+    }
+}
+/** Git could not resolve the range, or the diff is too large to surface. */
+export class ChangesInputError extends Error {
+    code = "E_CHANGES_INPUT";
+    constructor(message) {
+        super(message);
+        this.name = "ChangesInputError";
+    }
+}
+/** The production git runner: argv only, no shell, optional locks and prompts disabled. */
+export const execGitReadOnly = async (args, opts) => {
+    const result = await execFileAsync("git", args, {
+        cwd: opts.cwd,
+        env: { ...opts.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" },
+        maxBuffer: GIT_MAX_BUFFER,
+    });
+    return { stdout: result.stdout };
+};
+/** Parse `a..b`, `a...b` (symmetric) or a single `X` (meaning `X..HEAD`) into its resolved ends. */
+export function parseChangeRange(s) {
+    if (typeof s !== "string" || !RANGE_RE.test(s))
+        throw new ChangesArgsError(`invalid change range: ${JSON.stringify(s)}`);
+    const triple = s.indexOf("...");
+    const double = triple >= 0 ? -1 : s.indexOf("..");
+    let from;
+    let to;
+    let symmetric;
+    if (triple >= 0) {
+        from = s.slice(0, triple);
+        to = s.slice(triple + 3);
+        symmetric = true;
+    }
+    else if (double >= 0) {
+        from = s.slice(0, double);
+        to = s.slice(double + 2);
+        symmetric = false;
+    }
+    else {
+        from = s;
+        to = "HEAD";
+        symmetric = false;
+    }
+    for (const side of [from, to]) {
+        if (side === "" || side.startsWith("-") || side.includes("..") || side.includes("@{-")) {
+            throw new ChangesArgsError(`unsafe change range: ${JSON.stringify(s)}`);
+        }
+    }
+    return { from, to, symmetric };
+}
+/** Validate human change notes: at most 20, each 1-2000 chars, no NUL. Returns a copy. */
+export function validateChangeNotes(notes) {
+    if (notes.length > MAX_NOTES)
+        throw new ChangesArgsError(`at most ${MAX_NOTES} change notes are allowed`);
+    for (const note of notes) {
+        if (note.length < 1 || note.length > MAX_NOTE_LENGTH || note.includes("\u0000")) {
+            throw new ChangesArgsError(`each change note must be 1-${MAX_NOTE_LENGTH} characters and contain no NUL`);
+        }
+    }
+    return [...notes];
+}
+/** Read a git range (and/or notes) and build the `ChangeScope` the healer consumes. */
+export async function readChangeScope(o) {
+    const exec = o.exec ?? execGitReadOnly;
+    const notes = validateChangeNotes(o.notes);
+    const maxFiles = o.limits?.maxFiles ?? DEFAULT_MAX_FILES;
+    const maxBytes = o.limits?.maxBytes ?? DEFAULT_MAX_BYTES;
+    if (o.range === undefined) {
+        return { evidence: extractChangeEvidence("", notes), scanned: { files: 0, hunks: 0, skipped: [] } };
+    }
+    const { from, to, symmetric } = parseChangeRange(o.range);
+    const fromSha = await resolveCommit(exec, o.cwd, from);
+    const toSha = await resolveCommit(exec, o.cwd, to);
+    const baseSha = symmetric ? await mergeBase(exec, o.cwd, fromSha, toSha) : fromSha;
+    const headSha = toSha;
+    assertSha(baseSha);
+    assertSha(headSha);
+    const diffArgs = [
+        "-c",
+        "core.fsmonitor=",
+        "-c",
+        "diff.external=",
+        "diff",
+        "--no-ext-diff",
+        "--no-textconv",
+        "--no-color",
+        "-M",
+        "--unified=0",
+        `${baseSha}..${headSha}`,
+        "--",
+    ];
+    let stdout;
+    try {
+        ({ stdout } = await exec(diffArgs, { cwd: o.cwd, env: process.env }));
+    }
+    catch (error) {
+        throw new ChangesInputError(`git diff failed: ${messageOf(error)}`);
+    }
+    if (Buffer.byteLength(stdout, "utf8") > maxBytes) {
+        throw new ChangesInputError(`change diff exceeds ${maxBytes} bytes`);
+    }
+    const files = countDiffSections(stdout);
+    if (files > maxFiles) {
+        throw new ChangesInputError(`change diff touches ${files} files (max ${maxFiles})`);
+    }
+    return {
+        range: o.range,
+        baseSha,
+        headSha,
+        evidence: extractChangeEvidence(stdout, notes),
+        scanned: { files, hunks: countHunks(stdout), skipped: skippedPaths(stdout) },
+    };
+}
+async function resolveCommit(exec, cwd, rev) {
+    const args = ["rev-parse", "--verify", "--quiet", "--end-of-options", `${rev}^{commit}`];
+    let stdout;
+    try {
+        ({ stdout } = await exec(args, { cwd, env: process.env }));
+    }
+    catch (error) {
+        throw new ChangesInputError(`cannot resolve change revision ${JSON.stringify(rev)}: ${messageOf(error)}`);
+    }
+    const sha = stdout.trim();
+    if (!SHA_RE.test(sha))
+        throw new ChangesInputError(`cannot resolve change revision ${JSON.stringify(rev)}`);
+    return sha;
+}
+async function mergeBase(exec, cwd, shaA, shaB) {
+    let stdout;
+    try {
+        ({ stdout } = await exec(["merge-base", shaA, shaB], { cwd, env: process.env }));
+    }
+    catch (error) {
+        throw new ChangesInputError(`cannot find merge base: ${messageOf(error)}`);
+    }
+    const sha = stdout.trim();
+    if (!SHA_RE.test(sha))
+        throw new ChangesInputError(`cannot find merge base for ${shaA}...${shaB}`);
+    return sha;
+}
+function assertSha(sha) {
+    if (!SHA_RE.test(sha))
+        throw new ChangesInputError(`resolved revision is not a commit SHA: ${JSON.stringify(sha)}`);
+}
+function countDiffSections(diff) {
+    let count = 0;
+    for (const line of diff.split(/\r?\n/))
+        if (line.startsWith("diff --git "))
+            count++;
+    return count;
+}
+function countHunks(diff) {
+    let count = 0;
+    for (const line of diff.split(/\r?\n/))
+        if (line.startsWith("@@ "))
+            count++;
+    return count;
+}
+function skippedPaths(diff) {
+    const paths = [];
+    for (const line of diff.split(/\r?\n/)) {
+        const header = /^diff --git a\/(.*) b\/(.*)$/.exec(line);
+        if (!header)
+            continue;
+        const newPath = unquotePath(header[2]);
+        if (isSkippedChangePath(newPath))
+            paths.push(newPath);
+    }
+    return paths;
+}
+function unquotePath(value) {
+    const trimmed = value.trim();
+    if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"'))
+        return trimmed.slice(1, -1);
+    return trimmed;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=change-context.js.map

package/dist/change-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-context.js","sourceRoot":"","sources":["../src/change-context.ts"],"names":[],"mappings":"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"}

package/dist/check-api.d.ts

@@ -1,5 +1,5 @@
 import { type CheckResult, type RunCheckOptions } from "./check-types.js";
 export { affectedBy } from "./check-plan.js";
 export { BudgetMeter } from "./check-budget.js";
-export { type BudgetReport, CheckAiSetupError, type CheckFinding, type CheckGateways, type CheckItemReport, CheckPreflightError, type CheckResult, type CheckRunners, type ItemKind, type RunCheckOptions } from "./check-types.js";
+export { type BudgetReport, CheckAiSetupError, CheckArgsError, type CheckFinding, type CheckGateways, type CheckItemReport, CheckPreflightError, type CheckResult, type CheckRunners, type ItemKind, type RunCheckOptions } from "./check-types.js";
 export declare function runCheck(opts: RunCheckOptions): Promise<CheckResult>;

package/dist/check-api.js

@@ -1,8 +1,9 @@
+import { readFileSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { aggregateOf, formatUsageLine } from "@jevitate/ai-core";
 import { consolidate, diffRuns, findingKey, renderJUnit, renderReportMarkdown, renderSarif } from "@jevitate/findings";
-import { approvalsReport } from "./approval-provenance.js";
+import { approvalsReportVerified } from "./approval-provenance.js";
 import { loadCatalog } from "./catalog-api.js";
 import { runAdversarialCliMission, runCoverageMission, runExploration, runFeatureCliMission } from "./explore-api.js";
 import { runJourneyProgrammatically } from "./journey-api.js";
@@ -10,14 +11,18 @@ import { runUsabilityMission } from "./ux-api.js";
 import { runVerifyFix } from "./verify-fix-api.js";
 import { currentEngineInfo } from "./engine.js";
 import { loadRunFile, resolveBaseline, scanRuns, summarizeRun } from "./report-api.js";
-import { CheckAiSetupError } from "./check-types.js";
+import { CheckAiSetupError, CheckArgsError, CheckPreflightError } from "./check-types.js";
+import { brittleStepGate, testIdAttributesOf, testIdAttributesOrDefault } from "./locator-health-api.js";
+import { combineHealth, compareLocatorHealth, exceedsBrittleSteps, trendLine } from "./locator-health.js";
+import { findProjectDir } from "./project-dir.js";
 import { BudgetMeter } from "./check-budget.js";
-import { errorMessage, plan, prepareTarget } from "./check-plan.js";
+import { errorMessage, plan, prepareSelfHeal, prepareTarget } from "./check-plan.js";
+import { makeEvidenceSelfHealer } from "./self-heal-adapter.js";
 import { caseDetail, execute } from "./check-execute.js";
 import { clock } from "@jevitate/domain";
 export { affectedBy } from "./check-plan.js";
 export { BudgetMeter } from "./check-budget.js";
-export { CheckAiSetupError, CheckPreflightError } from "./check-types.js";
+export { CheckAiSetupError, CheckArgsError, CheckPreflightError } from "./check-types.js";
 const REAL_RUNNERS = {
     journey: runJourneyProgrammatically,
     goal: runExploration,
@@ -33,7 +38,8 @@ async function approvalDefects(opts, req) {
     const catalogs = [];
     for (const d of dirs)
         catalogs.push(await loadCatalog(req.catalogDir, d));
-    const report = approvalsReport(catalogs, req.allowedChannels);
+    // #469: a recorded pr-review approval counts only when the forge re-confirms it.
+    const report = await approvalsReportVerified(catalogs, req.allowedChannels, { catalogDir: req.catalogDir, ...(opts.approvalVerification ?? {}) });
     const defects = (report.requirement?.violations ?? []).map((v) => {
         const identity = { category: "approval", signal: `approval-${v.problem}`, control: `${v.kind} ${v.id}` };
         const key = findingKey(identity);
@@ -41,6 +47,90 @@ async function approvalDefects(opts, req) {
     });
     return { defects };
 }
+/**
+ * #470: the project's test-id convention for a check's Journey items. With the opt-in gate a malformed
+ * project config refuses the check (it would gate on a guessed convention); without it the defaults
+ * apply, as a run's result.json does.
+ */
+function checkTestIdAttributes(opts) {
+    const projectDir = opts.projectDir === undefined ? findProjectDir() : opts.projectDir;
+    if (opts.maxBrittleSteps === undefined)
+        return testIdAttributesOrDefault(projectDir);
+    try {
+        return testIdAttributesOf(projectDir);
+    }
+    catch (e) {
+        throw new CheckPreflightError(`--max-brittle-steps needs the project's testIdAttributes convention: ${errorMessage(e)}`);
+    }
+}
+/** #470: the gate's finding for one Journey item past `--max-brittle-steps` (hard: it fails the check). */
+function brittleDefect(journeyId, health, maxBrittleSteps) {
+    const identity = { category: "locator-health", signal: "brittle-steps", control: `journey ${journeyId}` };
+    const key = findingKey(identity);
+    const title = `Journey '${journeyId}': ${health.brittle} brittle locator step(s), more than --max-brittle-steps ${maxBrittleSteps}${health.line === undefined ? "" : ` (${health.line})`}`;
+    return { key, keys: [key], identity, category: "locator-health", severity: "hard", title, reproduce: `jevitate locator-health --journey ${journeyId}`, fingerprints: [], modes: [], occurrences: 1, runCount: 0, evidence: [], intermittent: false };
+}
+/** #470: the locator health a baseline run's result.json recorded, per Journey (the latest run of each wins). */
+function baselineLocatorHealths(runs) {
+    const out = new Map();
+    for (const run of runs) {
+        if (run.mode !== "journey")
+            continue;
+        try {
+            const json = JSON.parse(readFileSync(run.path, "utf8"));
+            const h = json.result?.locatorHealth;
+            if (typeof json.result?.journeyId === "string" && typeof h?.brittle === "number" && Array.isArray(h.steps))
+                out.set(json.result.journeyId, h);
+        }
+        catch {
+            // An unreadable baseline run has no locator health to compare against.
+        }
+    }
+    return out;
+}
+/** #470: one trend over several Journeys (the counts summed). */
+function sumTrends(trends) {
+    const sum = (f) => trends.reduce((n, t) => n + f(t), 0);
+    return {
+        improved: sum((t) => t.improved),
+        regressed: sum((t) => t.regressed),
+        unchanged: sum((t) => t.unchanged),
+        added: sum((t) => t.added),
+        removed: sum((t) => t.removed),
+        brittleDelta: sum((t) => t.brittleDelta),
+        changes: trends.flatMap((t) => t.changes),
+    };
+}
+const LOCATOR_WARNING_RULE = "jevitate/locator-health/brittle-locator";
+/**
+ * #470: advisory locator fixes as SARIF WARNINGS (never errors, never gating) — one result per element
+ * to fix, located at the suite file with the route as its logical location.
+ */
+function withLocatorWarnings(sarif, suggestions, suiteUri) {
+    if (suggestions.length === 0)
+        return sarif;
+    const [run, ...rest] = sarif.runs;
+    if (run === undefined)
+        return sarif;
+    const rule = { id: LOCATOR_WARNING_RULE, name: LOCATOR_WARNING_RULE.replace(/[^A-Za-z0-9]+/g, "_"), shortDescription: { text: "locator-health: a step's target misses the project's test-id convention" }, defaultConfiguration: { level: "warning" } };
+    const results = suggestions.map((s) => {
+        const journeys = [...new Set(s.occurrences.flatMap((o) => (o.journeyId === undefined ? [] : [o.journeyId])))];
+        return {
+            ruleId: LOCATOR_WARNING_RULE,
+            level: "warning",
+            message: { text: s.fix },
+            locations: [
+                {
+                    physicalLocation: { artifactLocation: { uri: suiteUri }, region: { startLine: 1 } },
+                    ...(s.route === undefined ? {} : { logicalLocations: [{ name: s.route, kind: "module" }] }),
+                },
+            ],
+            partialFingerprints: { jevitateFindingKey: `locator-health:${s.key}` },
+            properties: { category: "locator-health", severity: "advisory", gating: false, element: s.element, reasons: s.reasons, journeys, steps: s.occurrences.length },
+        };
+    });
+    return { ...sarif, runs: [{ ...run, tool: { ...run.tool, driver: { ...run.tool.driver, rules: [...run.tool.driver.rules, rule] } }, results: [...run.results, ...results] }, ...rest] };
+}
 export async function runCheck(opts) {
     const nowIso = opts.nowIso ?? (() => clock.nowIso());
     const startedAt = nowIso();
@@ -53,6 +143,18 @@ export async function runCheck(opts) {
     for (const t of opts.suite.targets)
         prepared.push(await prepareTarget(t, opts));
     const items = plan(prepared, opts.changedRoutes, opts);
+    // #453: refuse a bad self-heal request and read the change scope ONCE, before the first browser opens.
+    const heal = await prepareSelfHeal(opts);
+    // #470: the opt-in locator gate and the convention it measures against, before anything runs.
+    if (opts.maxBrittleSteps !== undefined) {
+        try {
+            brittleStepGate(opts.maxBrittleSteps);
+        }
+        catch (e) {
+            throw new CheckArgsError(errorMessage(e));
+        }
+    }
+    const testIdAttributes = items.some((i) => i.kind === "journey" && i.skipped === undefined) ? checkTestIdAttributes(opts) : undefined;
     let gw;
     const gateways = () => {
         if (opts.gateways === undefined)
@@ -67,7 +169,17 @@ export async function runCheck(opts) {
     const meter = new BudgetMeter(opts.suite.budget, { ...(opts.now === undefined ? {} : { now: opts.now }), costKnownZero: opts.aiMode === "fake" });
     const usage = async () => (gw === undefined ? undefined : (await gw).usage.snapshot());
     let n = 0;
-    const ctx = { opts, runners, resultsDir, gateways, engine, seq: () => String(++n) };
+    let healer;
+    const ctx = {
+        opts,
+        runners,
+        resultsDir,
+        gateways,
+        engine,
+        seq: () => String(++n),
+        ...(testIdAttributes === undefined ? {} : { testIdAttributes }),
+        ...(heal === undefined ? {} : { heal, healer: () => (healer ??= gateways().then((g) => makeEvidenceSelfHealer(g.gen, { usage: g.usage }))) }),
+    };
     const now = opts.now ?? clock.now;
     let exceeded;
     const executed = [];
@@ -109,7 +221,17 @@ export async function runCheck(opts) {
     }
     // #437 --require-approvals: each violation is a hard `approval` finding on the `approvals` item.
     const approvals = opts.requireApprovals === undefined ? undefined : await approvalDefects(opts, opts.requireApprovals);
-    const defects = [...consolidate(runs), ...(approvals?.defects ?? [])];
+    // #470 --max-brittle-steps: a Journey item past the threshold is a hard `locator-health` finding on that item.
+    const brittleOf = new Map();
+    if (opts.maxBrittleSteps !== undefined) {
+        executed.forEach(({ item, ex }, idx) => {
+            const health = ex?.locatorHealth;
+            if (item.kind === "journey" && health !== undefined && exceedsBrittleSteps(health, opts.maxBrittleSteps)) {
+                brittleOf.set(idx, brittleDefect(item.name, { brittle: health.brittle, ...(ex?.locatorDetail === undefined ? {} : { line: ex.locatorDetail.line }) }, opts.maxBrittleSteps));
+            }
+        });
+    }
+    const defects = [...consolidate(runs), ...(approvals?.defects ?? []), ...brittleOf.values()];
     let diff;
     let baselineRuns;
     if (opts.baseline !== undefined) {
@@ -123,6 +245,9 @@ export async function runCheck(opts) {
     }
     const entryOf = new Map(diff?.entries.map((e) => [e.key, e]) ?? []);
     const isGating = (d) => {
+        // #453: a proposed Journey revision (`pending`) is never a defect, whatever `gateAdvisory` says: it makes the check exit 5.
+        if (d.severity === "pending")
+            return false;
         if (d.severity !== "hard" && !opts.suite.gateAdvisory)
             return false;
         if (diff === undefined)
@@ -133,7 +258,7 @@ export async function runCheck(opts) {
     };
     const statusOf = (d) => d.keys.map((k) => entryOf.get(k)?.status).find((s) => s !== undefined);
     const gating = defects.filter(isGating);
-    const itemReports = executed.map(({ item, ex, durationMs }) => {
+    const itemReports = executed.map(({ item, ex, durationMs }, idx) => {
         const base = {
             target: item.t.target.name,
             kind: item.kind,
@@ -144,10 +269,18 @@ export async function runCheck(opts) {
         if (ex === undefined)
             return { ...base, status: "skipped", actions: 0, verdict: "skipped", gating: [] };
         const run = ex.resultPath === undefined ? undefined : runOf.get(ex.resultPath);
-        const own = run === undefined ? [] : gating.filter((d) => d.modes.some((m) => m.runs.some((r) => r.path === run.path)));
-        const verdict = ex.status === "error" ? "error" : own.length > 0 ? "failed" : "passed";
+        const brittle = brittleOf.get(idx);
+        const own = [
+            ...(run === undefined ? [] : gating.filter((d) => d.modes.some((m) => m.runs.some((r) => r.path === run.path)))),
+            ...(brittle !== undefined && gating.includes(brittle) ? [brittle] : []),
+        ];
+        // #453: a self-healed Journey that only proposed a revision is pending a person (never a pass).
+        const pending = ex.status === "ran" && ex.outcome === "healed-pending-review" && own.length === 0;
+        const verdict = ex.status === "error" ? "error" : own.length > 0 ? "failed" : pending ? "pending-review" : "passed";
         return {
             ...base,
+            ...(pending ? { proposal: { journeyId: item.name, ...(ex.proposal ?? {}) } } : {}),
+            ...(ex.healAttempts === undefined ? {} : { healAttempts: ex.healAttempts }),
             status: ex.status,
             actions: ex.actions,
             verdict,
@@ -157,19 +290,60 @@ export async function runCheck(opts) {
             ...(run === undefined ? {} : { runId: run.runId }),
             ...(ex.outcome === undefined ? {} : { outcome: ex.outcome }),
             ...(ex.goalOutcome === undefined ? {} : { goalOutcome: ex.goalOutcome }),
+            ...(ex.journeyHash === undefined ? {} : { journeyHash: ex.journeyHash }),
+            // #469: a baseline only from a clean run — a completed replay with no gating finding.
+            ...(ex.baseline === undefined || verdict !== "passed" ? {} : { baseline: ex.baseline }),
+            ...(ex.locatorHealth === undefined ? {} : { locatorHealth: ex.locatorHealth }),
         };
     });
+    // #470: locator health over the Journey items (advisory unless the gate is set), and its trend against --baseline.
+    const details = executed.flatMap(({ item, ex }) => item.kind === "journey" && ex?.locatorDetail !== undefined ? [{ name: item.name, detail: ex.locatorDetail }] : []);
+    const combined = combineHealth(details.map((d) => d.detail));
+    let locatorTrend;
+    if (baselineRuns !== undefined && details.length > 0) {
+        const before = baselineLocatorHealths(baselineRuns);
+        const trends = executed.flatMap(({ item, ex }) => {
+            const b = item.kind === "journey" && ex?.locatorHealth !== undefined ? before.get(item.name) : undefined;
+            return b === undefined || ex?.locatorHealth === undefined ? [] : [compareLocatorHealth(ex.locatorHealth, b)];
+        });
+        if (trends.length > 0) {
+            const t = sumTrends(trends);
+            locatorTrend = { improved: t.improved, regressed: t.regressed, unchanged: t.unchanged, added: t.added, removed: t.removed, brittleDelta: t.brittleDelta, line: trendLine(t) };
+        }
+    }
+    const locatorHealth = details.length === 0 && opts.maxBrittleSteps === undefined
+        ? undefined
+        : {
+            journeys: details.length,
+            stable: combined.stable,
+            brittle: combined.brittle,
+            ...(testIdAttributes === undefined ? {} : { testIdAttributes }),
+            ...(opts.maxBrittleSteps === undefined ? {} : { maxBrittleSteps: opts.maxBrittleSteps, exceeded: brittleOf.size > 0 }),
+            ...(details.length === 0 ? {} : { line: combined.line }),
+            ...(locatorTrend === undefined ? {} : { trend: locatorTrend }),
+        };
+    // Without the gate, each Journey item's fixes are JUnit/SARIF warnings (never failures).
+    const warningsOf = (i, idx) => {
+        if (opts.maxBrittleSteps !== undefined || i.kind !== "journey")
+            return [];
+        const ex = executed[idx]?.ex;
+        return (ex?.locatorDetail?.suggestions ?? []).map((s) => s.fix);
+    };
     if (approvals !== undefined) {
         const own = gating.filter((d) => approvals.defects.includes(d)).map((d) => d.key);
         itemReports.push({ target: "approvals", kind: "approvals", name: "require-approvals", status: "ran", actions: 0, durationMs: 0, verdict: own.length > 0 ? "failed" : "passed", gating: own });
     }
     const errors = itemReports.filter((i) => i.verdict === "error").length;
-    const exitCode = gating.length > 0 ? 1 : errors > 0 || exceeded !== undefined ? 2 : 0;
+    const pendingItems = itemReports.filter((i) => i.verdict === "pending-review");
+    const proposals = pendingItems.flatMap((i) => (i.proposal === undefined ? [] : [i.proposal]));
+    const gatingFindings = gating.length;
+    // Precedence 1 > 2 > 5 > 0: a defect or exhausted heal, then an item error / budget overrun, then a proposal awaiting review.
+    const exitCode = gatingFindings > 0 ? 1 : errors > 0 || exceeded !== undefined ? 2 : pendingItems.length > 0 ? 5 : 0;
     const junitPath = resolve(opts.junitPath ?? join(outDir, "junit.xml"));
     const sarifPath = resolve(opts.sarifPath ?? join(outDir, "jevitate.sarif"));
     const jsonPath = resolve(opts.jsonPath ?? join(outDir, "check.json"));
     const reportPath = join(outDir, "report.md");
-    const cases = itemReports.map((i) => {
+    const cases = itemReports.map((i, idx) => {
         const own = gating.filter((d) => i.gating.includes(d.key));
         const first = own[0];
         // #250: each gating finding's repro clip and screenshots, attached to the case CI shows.
@@ -184,6 +358,14 @@ export async function runCheck(opts) {
             status: i.verdict,
             ...(i.resultPath === undefined ? {} : { resultPath: i.resultPath }),
             ...(attachments.length === 0 ? {} : { attachments }),
+            ...(warningsOf(i, idx).length === 0 ? {} : { warnings: warningsOf(i, idx) }),
+            ...(i.verdict === "pending-review"
+                ? {
+                    type: "healed-pending-review",
+                    message: `proposed revision${i.proposal?.proposalId === undefined ? "" : ` ${i.proposal.proposalId}`} awaiting review`,
+                    ...(i.proposal?.path === undefined ? {} : { detail: i.proposal.path }),
+                }
+                : {}),
             ...(i.verdict === "failed" && first !== undefined
                 ? { type: first.category, message: `${own.length} gating finding(s): ${first.title}`, detail: caseDetail(own) }
                 : {}),
@@ -214,7 +396,7 @@ export async function runCheck(opts) {
         kind: "jevitate-check",
         suite: opts.suite.name,
         suitePath: opts.suite.path,
-        verdict: exitCode === 0 ? "pass" : "fail",
+        verdict: exitCode === 0 ? "pass" : exitCode === 5 ? "pending-review" : "fail",
         exitCode,
         engine,
         ...(opts.targetBuild === undefined ? {} : { targetBuild: opts.targetBuild }),
@@ -229,8 +411,11 @@ export async function runCheck(opts) {
             failed: itemReports.filter((i) => i.verdict === "failed").length,
             errors,
             skipped: itemReports.filter((i) => i.verdict === "skipped").length,
-            gatingFindings: gating.length,
+            gatingFindings,
+            pendingReview: pendingItems.length,
         },
+        ...(locatorHealth === undefined ? {} : { locatorHealth }),
+        proposals,
         ...(diff === undefined || baselineRuns === undefined ? {} : { diff: { baseline: baselineRuns.map(summarizeRun), summary: diff.summary } }),
         results: runs.map((r) => r.path),
         junitPath,
@@ -239,16 +424,21 @@ export async function runCheck(opts) {
         reportPath,
     };
     await writeFile(junitPath, renderJUnit(`jevitate check: ${opts.suite.name}`, cases, startedAt), "utf8");
-    const sarif = renderSarif({
+    const sarif = withLocatorWarnings(renderSarif({
         toolVersion: engine.version,
         engineCommit: engine.commit,
         ...(opts.targetBuild === undefined ? {} : { targetBuild: opts.targetBuild }),
         suiteUri: opts.suiteUri ?? opts.suite.path,
         automationId: `jevitate-check/${opts.suite.name}/`,
         findings: defects.map((d) => ({ defect: d, gating: gating.includes(d), ...(statusOf(d) === undefined ? {} : { status: statusOf(d) }) })),
-    });
+    }), opts.maxBrittleSteps === undefined ? combined.suggestions : [], opts.suiteUri ?? opts.suite.path);
     await writeFile(sarifPath, `${JSON.stringify(sarif, null, 2)}\n`, "utf8");
     await writeFile(reportPath, renderReportMarkdown({ title: `jevitate check: ${opts.suite.name} — ${result.verdict}`, runs, defects, ...(diff === undefined ? {} : { diff }) }) +
+        (proposals.length === 0
+            ? ""
+            : `\n## Proposed Journey revisions\n\nA self-heal re-ran these failed Journeys against the change and proposed a revision. Nothing passes until a person accepts it.\n\n${proposals
+                .map((p) => `- \`${p.journeyId}\`${p.proposalId === undefined ? "" : ` — proposal \`${p.proposalId}\``}${p.path === undefined ? "" : ` (${p.path})`}: \`jevitate journey review ${p.journeyId}\``)
+                .join("\n")}\n`) +
         (suiteUsage === undefined ? "" : `\n## Model cost\n\n${formatUsageLine(suiteUsage)}\n`), "utf8");
     await writeFile(jsonPath, `${JSON.stringify({ v: 1, ok: true, data: result }, null, 2)}\n`, "utf8");
     return result;