@jevitate/cli 0.11.0 → 0.12.0

package/dist/journey-review.js

@@ -2,7 +2,7 @@ import { contentHash } from "@jevitate/domain";
 import { describeProvenance } from "./approval-provenance.js";
 import { SECRET_PARAM_NAME_RE, describeStep, flatJourneySteps, isNoClaimExpect, isOwnTargetVisible, journeyAssertions, journeyEndState, journeyRunParams, journeyWriteSteps, lintJourney, secretParamNames, } from "@jevitate/journey";
 import { renderFindings } from "./catalog-review.js";
-import { SafetyPolicy, describeCheck } from "@jevitate/explore";
+import { SafetyPolicy, describeCheck, explainCheck } from "@jevitate/explore";
 import { navigateUrlParams, writeClassifier } from "@jevitate/recording";
 /**
  * #432 — `jevitate journey review <id>`: one human-readable review sheet for promotion sign-off.
@@ -45,7 +45,7 @@ function reviewTarget(t) {
 }
 /** Does the field read as a credential (its name, label or test id)? Its literal value is then never shown. */
 function secretLooking(t) {
-    return [t.name, t.label, t.testId, t.text].some((s) => s !== undefined && SECRET_PARAM_NAME_RE.test(s));
+    return [t.name, t.label, t.testId, t.text, t.display?.name].some((s) => s !== undefined && SECRET_PARAM_NAME_RE.test(s));
 }
 function hideValue(v) {
     return "var" in v || v.redacted ? v : { redacted: true, length: 0 };
@@ -91,6 +91,28 @@ function evidenceLine(e) {
     const where = e.file === undefined ? "" : ` (${e.file}${e.line === undefined ? "" : `:${e.line}`})`;
     return `${e.kind}${change}${where}`;
 }
+/** A target's exact locator, e.g. `data-testid=publish-now` or `role=button name="Save"`. */
+function locatorSpec(t) {
+    if (t.testId !== undefined)
+        return `${t.testIdAttr ?? "data-testid"}=${t.testId}`;
+    const parts = [
+        t.role === undefined ? null : `role=${t.role}`,
+        t.name === undefined ? null : `name="${t.name}"`,
+        t.label === undefined ? null : `label="${t.label}"`,
+        t.text === undefined ? null : `text="${t.text}"`,
+        t.css === undefined ? null : `css=${t.css}`,
+    ].filter((x) => x !== null);
+    return parts.join(" ");
+}
+/**
+ * #497: a self-heal proposal changes a step's LOCATOR, which a recorded display label hides
+ * (`click "Import"` before and after) — so a proposal's step shows its exact locator too.
+ */
+function withLocator(step) {
+    const target = targetOf(step);
+    const spec = target === undefined ? "" : locatorSpec(target);
+    return spec === "" ? describeStep(sanitized(step)) : `${describeStep(sanitized(step))} · locator ${spec}`;
+}
 function buildProposal(ctx, journeyId) {
     const p = ctx.proposal;
     return {
@@ -103,8 +125,8 @@ function buildProposal(ctx, journeyId) {
         changes: { ...(p.changes.range === undefined ? {} : { range: p.changes.range }), ...(p.changes.baseSha === undefined ? {} : { baseSha: p.changes.baseSha }), ...(p.changes.headSha === undefined ? {} : { headSha: p.changes.headSha }), notes: [...p.changes.notes] },
         steps: p.steps.map((s) => ({
             number: s.index + 1,
-            before: describeStep(s.before),
-            after: describeStep(s.after),
+            before: withLocator(s.before),
+            after: withLocator(s.after),
             hypothesis: s.justification.hypothesis + (s.justification.anchorNotInChange === true ? " (the new anchor is not named by any change evidence)" : ""),
             evidence: s.justification.evidence.map(evidenceLine),
             screenshots: [...(s.screenshots ?? [])],
@@ -113,15 +135,34 @@ function buildProposal(ctx, journeyId) {
         acceptCommand: `jevitate journey promote ${journeyId} --proposal ${p.proposalId} --reviewed-hash ${p.proposedHash}`,
     };
 }
+/**
+ * 0.12.0 review M4: the short exact locator shown beside a step's recorded display label — the
+ * test id when there is one, else role and name (else the full `locatorSpec`). A display label is
+ * free text a shared Journey can set (`{testId: "delete-account", display: {name: "Cancel"}}`), so
+ * the approver sees what the step really acts on. Undefined when the target has no display label.
+ */
+function displayedLocator(t) {
+    if (t === undefined || t.display === undefined)
+        return undefined;
+    const short = t.testId !== undefined
+        ? { testId: t.testId, ...(t.testIdAttr === undefined ? {} : { testIdAttr: t.testIdAttr }) }
+        : t.role !== undefined || t.name !== undefined
+            ? { ...(t.role === undefined ? {} : { role: t.role }), ...(t.name === undefined ? {} : { name: t.name }) }
+            : t;
+    const spec = locatorSpec(short);
+    return spec === "" ? undefined : spec;
+}
 function buildSteps(journey) {
     return flatJourneySteps(journey).map(({ index, recorded }) => {
         const step = recorded.step;
         const target = reviewTarget(targetOf(step));
         const assertion = ownAssertion(step);
+        const locator = displayedLocator(targetOf(step));
         return {
             number: index + 1,
             kind: step.kind,
             action: describeStep(sanitized(step)),
+            ...(locator === undefined ? {} : { locator }),
             ...(target === undefined ? {} : { target }),
             ...(recorded.objective === undefined || recorded.objective.trim() === "" ? {} : { objective: recorded.objective }),
             ...(recorded.expectedResult === undefined || recorded.expectedResult.trim() === "" ? {} : { expectedResult: recorded.expectedResult }),
@@ -328,13 +369,25 @@ export function buildJourneyReview(journey, ctx = {}) {
     const stepAssertions = journeyAssertions(journey).flatMap((site) => {
         if (site.where === "end-state")
             return [];
+        const explained = explainCheck(site.check);
         if (site.where === "step-request")
-            return [{ step: site.step, check: describeCheck(site.check), weak: false }];
+            return [{ step: site.step, check: describeCheck(site.check), weak: explained.weak, text: explained.text }];
         const step = flat[site.step - 1]?.recorded.step;
-        const weak = site.check.assertion.kind === "visible" || (site.field === "expect" && step !== undefined && (isOwnTargetVisible(step) || isNoClaimExpect(step)));
-        return [{ step: site.step, check: describeCheck(site.check), weak }];
+        const weak = explained.weak || site.check.assertion.kind === "visible" || (site.field === "expect" && step !== undefined && (isOwnTargetVisible(step) || isNoClaimExpect(step)));
+        return [{ step: site.step, check: describeCheck(site.check), weak, text: explained.text }];
     });
-    return {
+    const endStateChecks = journeyEndState(journey);
+    const endStateExplained = endStateChecks.map(explainCheck);
+    const anchors = (m.anchors ?? []).map((a) => ({ name: a.name, step: a.step }));
+    const writeRequests = buildWriteRequests(journey);
+    const enriched = steps.map((st) => {
+        const checks = stepAssertions.filter((a) => a.step === st.number).map((a) => ({ text: a.text, weak: a.weak }));
+        const mine = anchors.filter((a) => a.step === st.number).map((a) => a.name);
+        const rec = flat[st.number - 1]?.recorded.step;
+        const file = rec !== undefined && rec.kind === "upload" ? describeFile(sanitized(rec)) : undefined;
+        return { ...st, ...(checks.length === 0 ? {} : { checks }), ...(mine.length === 0 ? {} : { anchors: mine }), ...(file === undefined ? {} : { file }) };
+    });
+    const review = {
         id: m.id,
         name: m.name,
         promoted: m.promoted,
@@ -343,6 +396,7 @@ export function buildJourneyReview(journey, ctx = {}) {
             ...(m.goal === undefined ? {} : { goal: m.goal }),
             ...(m.persona === undefined ? {} : { persona: m.persona }),
             ...(m.role === undefined ? {} : { role: m.role }),
+            ...((journey.recording.intent ?? "").trim() === "" ? {} : { intent: journey.recording.intent.trim() }),
             requiresAuth: m.requiresAuth === true,
             preconditions: (m.preconditions ?? []).map((p) => p.description),
             successCriteria: (m.successCriteria ?? []).map((c) => ({
@@ -351,8 +405,8 @@ export function buildJourneyReview(journey, ctx = {}) {
             })),
             missingIntent,
         },
-        steps,
-        sideEffects: { writeRequests: buildWriteRequests(journey), riskyControls: buildRiskyControls(journey, ctx.safety), origins: buildOrigins(journey) },
+        steps: enriched,
+        sideEffects: { writeRequests, riskyControls: buildRiskyControls(journey, ctx.safety), origins: buildOrigins(journey) },
         inputs: {
             params: paramNames.map((name) => {
                 const description = described.get(name);
@@ -361,7 +415,8 @@ export function buildJourneyReview(journey, ctx = {}) {
             secrets: (m.secretRefs ?? []).map((r) => ({ field: r.field, manager: r.manager, origin: r.origin })),
         },
         proof: {
-            endState: journeyEndState(journey).map(describeCheck),
+            endState: endStateChecks.map(describeCheck),
+            endStateText: endStateExplained.map((e) => e.text),
             stepAssertions,
             lint: {
                 errors: findings.filter((f) => f.level === "error").length,
@@ -392,8 +447,118 @@ export function buildJourneyReview(journey, ctx = {}) {
         ...(ctx.anchorIssues === undefined ? {} : { anchorWarnings: anchorWarningsOf(ctx.anchorIssues) }),
         ...(ctx.locatorHealth === undefined ? {} : { locatorHealth: locatorHealthOf(ctx.locatorHealth) }),
         ...(ctx.proposal === undefined ? {} : { proposal: buildProposal(ctx.proposal, m.id) }),
+        ...(anchors.length === 0 ? {} : { anchors }),
         contentHash: hash,
     };
+    return { ...review, attention: buildAttention(review, endStateExplained.filter((e) => e.weak).map((e) => e.text), m.goal) };
+}
+/** An upload step's file in words: the recorded path, `{var}` or «redacted». */
+function describeFile(step) {
+    const f = step.file;
+    if (f === undefined)
+        return undefined;
+    if ("var" in f)
+        return `{${f.var}}`;
+    return f.redacted ? "«redacted»" : f.value;
+}
+/** Step numbers as ranges: 1, 2, 3, 5 becomes `1–3, 5`. */
+export function stepRanges(numbers) {
+    const sorted = [...new Set(numbers)].sort((a, b) => a - b);
+    const parts = [];
+    for (let i = 0; i < sorted.length;) {
+        let j = i;
+        while (j + 1 < sorted.length && sorted[j + 1] === sorted[j] + 1)
+            j++;
+        parts.push(j === i ? `${sorted[i]}` : `${sorted[i]}–${sorted[j]}`);
+        i = j + 1;
+    }
+    return parts.join(", ");
+}
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+/** Everything that needs the reviewer's decision, warnings first (stable within a severity). */
+function buildAttention(r, weakEndState, goal) {
+    const out = [];
+    const warn = (text, hint) => void out.push({ severity: "warn", text, ...(hint === undefined ? {} : { hint }) });
+    const info = (text, hint) => void out.push({ severity: "info", text, ...(hint === undefined ? {} : { hint }) });
+    const weakSteps = [...new Set(r.proof.stepAssertions.filter((a) => a.weak).map((a) => a.step))];
+    if (weakSteps.length === 1)
+        warn(`Step ${stepRanges(weakSteps)} proves nothing: its check passes even if the step fails`);
+    else if (weakSteps.length > 1)
+        warn(`Steps ${stepRanges(weakSteps)} prove nothing: their checks pass even if the step fails`);
+    for (const t of weakEndState)
+        warn(`An end-state check proves nothing: ${t}`);
+    const annotate = `jevitate journey annotate ${r.id}`;
+    const noGoal = (goal ?? "").trim() === "";
+    const noCriteria = r.summary.successCriteria.length === 0;
+    if (noGoal && noCriteria)
+        warn("No goal or success criteria written", annotate);
+    else if (noGoal)
+        warn("No goal written", annotate);
+    else if (noCriteria)
+        warn("No success criteria written", annotate);
+    for (const f of r.proof.lint.findings) {
+        warn(`Lint ${f.level} ${f.rule}${f.step === undefined ? "" : ` (step ${f.step})`}: ${f.message}`);
+    }
+    for (const c of r.sideEffects.riskyControls) {
+        const text = `Risky control at step ${c.step}: ${c.role === undefined ? "" : `${c.role} `}"${c.control}" (${c.risk})`;
+        if (c.waivedBy === undefined)
+            warn(text);
+        else
+            info(`${text}, exempted by allowControl`);
+    }
+    if (r.catalog !== undefined) {
+        if (r.catalog.unvetted.length > 0)
+            warn(`Unvetted catalog links: ${r.catalog.unvetted.join(", ")}`, `approve them, or promote with --accept-unvetted "<reason>"`);
+        if (r.catalog.needsReReview.length > 0)
+            warn(`Catalog links need re-review: ${r.catalog.needsReReview.join("; ")}`);
+    }
+    for (const f of r.findings ?? []) {
+        if (f.analyzer === "catalog-analysis")
+            continue;
+        if (f.severity !== "info")
+            warn(f.message, f.fix);
+        else if (f.analyzer === "readiness" || f.analyzer === "readiness-jev")
+            info(f.message, f.fix);
+    }
+    const c = r.changeSinceApproval;
+    if ((c.kind === "diff" || c.kind === "snapshot-missing") && c.changed) {
+        if (c.kind === "diff") {
+            const bit = (sign, n, word, many) => (n === 0 ? [] : [`${sign}${plural(n, word, many)}`]);
+            const parts = [
+                ...bit("+", c.steps.added.length, "step"),
+                ...bit("−", c.steps.removed.length, "step"),
+                ...bit("+", c.assertions.added.length, "check"),
+                ...bit("−", c.assertions.removed.length, "check"),
+                ...bit("+", c.sideEffects.added.length, "side effect"),
+                ...bit("−", c.sideEffects.removed.length, "side effect"),
+            ];
+            warn(`Changed since approval${parts.length === 0 ? "" : `: ${parts.join(", ")}`}${c.stepIdOnly === true ? " (step ids only)" : ""}`, "--full lists every change");
+        }
+        else {
+            warn(`Changed since approval (its approved snapshot is missing, so only the hash differs)${c.stepIdOnly === true ? " (step ids only)" : ""}`);
+        }
+    }
+    for (const w of r.anchorWarnings ?? [])
+        warn(`Anchor ${w.severity} ${w.path}${w.step === undefined ? "" : ` (step ${w.step})`}: ${w.message}`, w.fix);
+    if (r.proposal !== undefined) {
+        const p = r.proposal;
+        if (p.stale || p.problem !== undefined)
+            warn(`A self-heal proposal is pending but cannot be accepted: ${p.stale ? "the Journey changed since" : p.problem}`);
+        else
+            warn(`A self-heal proposal changes ${plural(p.steps.length, "step")}`, p.acceptCommand);
+    }
+    const v = r.proof.verify;
+    if (v.status === "not-verified")
+        info("Not mutation-tested", `jevitate journey verify ${r.id} --mutate`);
+    else if (v.stale)
+        warn("The mutation proof is out of date: the Journey changed after it ran", `jevitate journey verify ${r.id} --mutate`);
+    else if (v.verdict === "insensitive")
+        warn("Mutation proof: some checks cannot fail", `jevitate journey verify ${r.id} --mutate`);
+    if (r.proof.acceptedWeak !== undefined)
+        info(`Weak checks were accepted: "${r.proof.acceptedWeak.reason}"`);
+    if (r.locatorHealth !== undefined && r.locatorHealth.brittle > 0)
+        info(`${plural(r.locatorHealth.brittle, "step")} on brittle locators`, "--full lists the fixes");
+    return [...out.filter((a) => a.severity === "warn"), ...out.filter((a) => a.severity === "info")];
 }
 /** #437: a copy of an approval's provenance (the sheet never shares the Journey's objects). */
 function copyProvenance(p) {
@@ -454,125 +619,374 @@ function prLines(p) {
     ];
     return [`Pull-request approval: ${parts.join(" · ")}`];
 }
-function renderSheet(r, style) {
+const DEFAULT_WIDTH = 100;
+const NB = " ";
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+/** `2026-10-11T08:33:26.979Z` as `11 Oct 2026 08:33 UTC` — parsed, not locale-formatted, so it is deterministic. */
+export function humanTime(iso) {
+    const m = /^(\d{4})-(\d\d)-(\d\d)T(\d\d):(\d\d)/.exec(iso);
+    if (m === null)
+        return iso;
+    return `${Number(m[3])} ${MONTHS[Number(m[2]) - 1] ?? m[2]} ${m[1]} ${m[4]}:${m[5]} UTC`;
+}
+/** Spaces inside a command or hash must not become line breaks. */
+const nb = (s) => s.replace(/ /g, NB);
+/** Wraps `text` after `prefix`; continuation lines are indented `hang` columns. Words (and nb-joined commands) are never cut. */
+function wrapText(prefix, text, width, hang = prefix.length) {
+    const words = text.split(" ").filter((w) => w !== "");
+    const lines = [];
+    let cur = prefix;
+    let empty = true;
+    for (const w of words) {
+        if (!empty && cur.length + 1 + w.length > width) {
+            lines.push(cur);
+            cur = " ".repeat(hang);
+            empty = true;
+        }
+        cur += `${empty ? "" : " "}${w}`;
+        empty = false;
+    }
+    lines.push(cur);
+    return lines.map((l) => l.replaceAll(NB, " ").trimEnd());
+}
+const HEADERS = ["NEEDS YOUR ATTENTION", "WHAT IT DOES", "STEPS", "PROVES AT THE END", "WRITES", "CLEAR", "APPROVE", "INPUTS", "PROPOSED REVISION (SELF-HEAL)", "DETAIL", "Review"];
+function paint(line, color) {
+    if (!color)
+        return line;
+    const header = HEADERS.find((h) => line.startsWith(h) && (line.length === h.length || line[h.length] === " "));
+    const body = line.replaceAll("⚠", "\u001b[33m⚠\u001b[0m").replaceAll("✓", "\u001b[32m✓\u001b[0m");
+    return header === undefined ? body : `\u001b[1m${header}\u001b[0m${body.slice(header.length)}`;
+}
+function renderSheet(r, style, opts = {}) {
     const md = style === "markdown";
+    const width = Math.max(40, opts.width ?? DEFAULT_WIDTH);
+    const full = opts.full === true;
     const code = (s) => (md ? `\`${s.replace(/`/g, "'")}\`` : s);
-    const h1 = (s) => (md ? `# ${s}` : `${s}\n${"=".repeat(Math.min(s.length, 80))}`);
-    const h2 = (s) => (md ? `## ${s}` : `${s.toUpperCase()}`);
-    const h3 = (s) => (md ? `### ${s}` : `${s}:`);
     const em = (s) => (md ? `_${s}_` : s);
-    const li = (s, depth = 0) => `${"  ".repeat(md ? depth : depth + 1)}- ${s}`;
     const out = [];
-    const section = (...lines) => {
-        out.push(...lines, "");
+    /** One item: wrapped and hanging in text, a single line in Markdown. */
+    const put = (prefix, text, hang) => {
+        if (md)
+            out.push(`${prefix}${text}`.replaceAll(NB, " "));
+        else
+            out.push(...wrapText(prefix, text, width, hang));
     };
-    const list = (items, none) => (items.length === 0 ? [li(em(none))] : items.map((i) => li(i)));
-    section(h1(`Journey review: ${r.name} (${r.id})`), "", `Content hash: ${code(r.contentHash)}`, `Status: ${r.promoted ? "promoted" : "not promoted"}${r.approval === undefined ? "" : ` · last approved ${r.approval.at} — ${describeProvenance(r.approval.provenance)}`}`, ...prLines(r.approval?.provenance));
-    const s = r.summary;
-    section(h2("Summary"), "", ...(s.description === undefined ? [] : [li(`Description: ${s.description}`)]), li(`Goal: ${s.goal ?? em("none")}`), ...(s.persona === undefined ? [] : [li(`Persona: ${s.persona}`)]), ...(s.role === undefined ? [] : [li(`Runs as: ${s.role}`)]), ...(s.requiresAuth ? [li("Needs an authenticated session")] : []), ...(s.preconditions.length === 0 ? [] : [li("Preconditions:"), ...s.preconditions.map((p) => li(p, 1))]), li("Success criteria:"), ...(s.successCriteria.length === 0
-        ? [li(em("none"), 1)]
-        : s.successCriteria.map((c) => li(`${c.description}${c.check === undefined ? "" : ` (checked by ${code(c.check)})`}`, 1))), ...(s.missingIntent.length === 0 ? [] : [li("Missing intent:"), ...s.missingIntent.map((w) => li(`⚠ ${w}`, 1))]));
-    const stepLinesOut = [];
-    for (const st of r.steps) {
-        const target = st.target === undefined ? "" : ` — target: ${[st.target.role, st.target.name === undefined ? undefined : `"${st.target.name}"`].filter((x) => x !== undefined).join(" ")}`;
-        stepLinesOut.push(`${md ? "" : "  "}${st.number}. ${md ? `**${st.action}**` : st.action}${target}`);
-        const sub = (t) => {
-            stepLinesOut.push(`${md ? "   " : "     "}- ${t}`);
-        };
-        sub(`Objective: ${st.objective ?? em("none")}`);
-        if (st.expectedResult !== undefined)
-            sub(`Expected result: ${st.expectedResult}`);
-        if (st.assertion !== undefined)
-            sub(`Checks: ${code(st.assertion)}`);
-        if (st.params.length > 0)
-            sub(`Params: ${st.params.map(code).join(", ")}`);
-    }
-    section(h2("Steps"), "", ...(stepLinesOut.length === 0 ? [li(em("no steps"))] : stepLinesOut));
-    const fx = r.sideEffects;
-    section(h2("Side effects"), "", h3("Write requests"), ...list(fx.writeRequests.map((w) => `${code(`${w.method} ${w.endpoint}`)} — ${w.source === "recorded" ? `recorded at step ${w.step}` : w.source === "expect-request" ? `expected at step ${w.step}` : "end-state check"}`), "none expected"), "", h3("Controls matching safety rules"), ...list(fx.riskyControls.map((c) => `step ${c.step}: ${c.role === undefined ? "" : `${c.role} `}"${c.control}" — ${c.risk} [${code(c.ruleId)}]${c.waivedBy === undefined ? "" : ` (exempted by allowControl ${code(c.waivedBy)})`}`), "none"), "", h3("Origins"), ...list(fx.origins.map(code), "none"));
-    section(h2("Inputs"), "", h3("Parameters"), ...list(r.inputs.params.map((p) => `${code(p.name)}${p.secret ? " (secret)" : ""}${p.description === undefined ? "" : ` — ${p.description}`}`), "none"), "", h3("Secret references"), ...list(r.inputs.secrets.map((x) => `${code(x.field)} from ${x.manager} on ${x.origin}`), "none"));
-    const p = r.proof;
-    const verify = p.verify.status === "not-verified"
-        ? `not verified — ${p.verify.hint}`
-        : `${p.verify.verdict} (${p.verify.at})${p.verify.stale ? " — STALE: the Journey changed after this proof ran" : ""}${p.verify.reason === undefined ? "" : ` — ${p.verify.reason}`}: ${Object.entries(p.verify.summary)
-            .map(([k, v]) => `${v} ${k}`)
-            .join(", ")}`;
-    section(h2("Proof"), "", h3("End-state checks"), ...list(p.endState.map(code), "none"), "", h3("Per-step assertions"), ...list(p.stepAssertions.map((a) => `step ${a.step}: ${code(a.check)}${a.weak ? " (weak: proves nothing about the step's effect)" : ""}`), "none"), "", h3(`Lint: ${p.lint.errors} error(s), ${p.lint.warnings} warning(s)`), ...list(p.lint.findings.map((f) => `${f.level} ${f.rule}${f.step === undefined ? "" : ` (step ${f.step})`}: ${f.message}`), "no findings"), ...(p.acceptedWeak === undefined ? [] : ["", `Accepted weak: "${p.acceptedWeak.reason}" (waived: ${p.acceptedWeak.rules.join(", ")})`]), "", `Mutation proof: ${verify}`);
+    const gap = () => void out.push("");
+    /** A section header: caps in text, a heading in Markdown. */
+    const head = (label, title = label.charAt(0) + label.slice(1).toLowerCase()) => {
+        if (!md)
+            out.push(label);
+        else
+            out.push(`## ${title}`, "");
+    };
+    const bullet = md ? "- " : "  ";
+    const cmd = (c) => (md ? code(c) : nb(c));
+    // ── Header
+    const prov = r.approval?.provenance;
     const c = r.changeSinceApproval;
-    const change = [];
-    if (c.kind === "first-approval")
-        change.push(em("first approval — nothing approved before"));
-    else if (c.kind === "no-record")
-        change.push(em("promoted before approvals were recorded — no approved version to compare with"));
-    else if (c.kind === "snapshot-missing") {
-        change.push(`Approved${c.approvedAt === undefined ? "" : ` ${c.approvedAt}`} as ${code(c.approvedHash)}; its snapshot is missing — ${c.changed ? "the Journey CHANGED since" : "unchanged since"}`);
-        if (c.stepIdOnly === true)
-            change.push(li(STEP_ID_ONLY_LABEL));
+    const changed = (c.kind === "diff" || c.kind === "snapshot-missing") && c.changed;
+    const plainApproval = prov !== undefined && prov.channel === "tty" && prov.agentSignals.filter((x) => !/not.?tty/i.test(x)).length === 0;
+    const approvedBy = prov?.user === undefined ? "" : ` by ${prov.user}`;
+    const status = !r.promoted
+        ? "not promoted"
+        : r.approval === undefined
+            ? "promoted (no approval recorded)"
+            : `approved ${humanTime(r.approval.at)}${plainApproval ? `${approvedBy} (terminal)` : ` — ${describeProvenance(prov)}`} · ${nb(changed ? "CHANGED since approval" : "unchanged since approval")}`;
+    if (md)
+        out.push(`# Review: ${r.name}`, "", `**${r.id}** · ${status}`);
+    else {
+        put("Review  ", r.name);
+        put("        ", `${r.id} · ${status}`);
+    }
+    for (const l of prLines(prov))
+        put(md ? "" : "        ", l);
+    gap();
+    // ── Needs your attention
+    const attention = r.attention ?? [];
+    if (attention.length === 0) {
+        if (md)
+            out.push("## Needs your attention", "", "Nothing — every gate is clear.");
+        else
+            out.push("NEEDS YOUR ATTENTION  nothing — every gate is clear");
     }
     else {
-        change.push(`Approved${c.approvedAt === undefined ? "" : ` ${c.approvedAt}`} as ${code(c.approvedHash)} — ${c.changed ? "CHANGED since" : "unchanged since"}`);
-        if (c.stepIdOnly === true)
-            change.push(li(STEP_ID_ONLY_LABEL));
-        for (const [label, d] of [
-            ["Steps", c.steps],
-            ["Assertions", c.assertions],
-            ["Side effects", c.sideEffects],
-        ]) {
-            if (d.added.length === 0 && d.removed.length === 0)
-                continue;
-            change.push("", h3(label), ...d.removed.map((l) => li(`− ${l}`)), ...d.added.map((l) => li(`+ ${l}`)));
+        head("NEEDS YOUR ATTENTION", "Needs your attention");
+        for (const a of attention) {
+            const icon = a.severity === "warn" ? "⚠" : "○";
+            const hint = a.hint === undefined ? "" : ` → ${/^(jevitate|--)/.test(a.hint) ? cmd(a.hint) : a.hint}`;
+            put(`${bullet}${icon} `, `${a.text}${hint}`, bullet.length + 2);
         }
     }
-    section(h2("Change since last approval"), "", ...change);
-    // #466 / #470: anchor-rule warnings and brittle steps, each with its fix.
-    if (r.anchorWarnings !== undefined && r.anchorWarnings.length > 0) {
-        section(h2("Anchor rules (#466)"), "", ...r.anchorWarnings.map((w) => li(`${w.severity} ${w.path}${w.step === undefined ? "" : ` (step ${w.step})`}: ${w.message}${w.fix === undefined ? "" : ` — fix: ${w.fix}`}`)));
+    gap();
+    // ── What it does
+    const s = r.summary;
+    const wid = [];
+    const primary = s.goal ?? s.intent ?? s.description;
+    head("WHAT IT DOES", "What it does");
+    if (primary !== undefined)
+        put(bullet, primary);
+    if (s.goal !== undefined && s.intent !== undefined && s.intent !== s.goal && full)
+        put(bullet, s.intent);
+    if (s.description !== undefined && s.description !== primary && full)
+        put(bullet, s.description);
+    for (const cr of s.successCriteria)
+        put(bullet, `Success: ${cr.description}${cr.check === undefined || !full ? "" : ` (checked by ${code(cr.check)})`}`);
+    for (const pc of s.preconditions)
+        put(bullet, `Needs: ${pc}`);
+    if (s.persona !== undefined)
+        wid.push(`persona ${s.persona}`);
+    if (s.role !== undefined)
+        wid.push(`runs as ${s.role}`);
+    if (s.requiresAuth)
+        wid.push("Signed in");
+    wid.push(...r.sideEffects.origins.slice(0, 1));
+    const files = r.steps.flatMap((st) => (st.file === undefined ? [] : [st.file]));
+    if (wid.length > 0)
+        put(bullet, wid.join(" · "));
+    if (files.length > 0)
+        put(bullet, `Uploads ${files.map(nb).join(", ")}`);
+    gap();
+    // ── Inputs (only when present)
+    if (r.inputs.params.length > 0 || r.inputs.secrets.length > 0) {
+        head("INPUTS", "Inputs");
+        if (r.inputs.params.length > 0)
+            put(bullet, `Parameters: ${r.inputs.params.map((p) => `${code(p.name)}${p.secret ? " (secret)" : ""}${p.description === undefined ? "" : ` — ${p.description}`}`).join("; ")}`);
+        for (const x of r.inputs.secrets)
+            put(bullet, `Secret ${code(x.field)} from ${x.manager} on ${x.origin}`);
+        gap();
     }
-    if (r.locatorHealth !== undefined) {
-        const lh = r.locatorHealth;
-        section(h2("Locator health (advisory)"), "", lh.line, "", ...(lh.brittleSteps.length === 0
-            ? [li(em("no brittle steps"))]
-            : lh.brittleSteps.map((b) => li(`step ${b.index + 1}${b.stepId === undefined ? "" : ` [${b.stepId}]`} ${b.kind} ${code(b.locator)}${b.route === undefined ? "" : ` on ${b.route}`} — ${b.reasons.join("; ")} — fix: ${b.fix}`))));
+    // ── Steps
+    if (r.steps.length > 0) {
+        head("STEPS", "Steps");
+        const numW = String(r.steps.length).length;
+        for (const st of r.steps) {
+            const anchors = (st.anchors ?? []).map((a) => `⚓ ${a}`).join(" ");
+            const target = full && st.target !== undefined ? ` — target: ${[st.target.role, st.target.name === undefined ? undefined : `"${st.target.name}"`].filter((x) => x !== undefined).join(" ")}` : "";
+            const lead = md ? `${st.number}. ` : `  ${String(st.number).padStart(numW)}  `;
+            const prefixLen = lead.length;
+            // M4: a labelled step's exact locator follows its label, so a spoofed label cannot hide it.
+            const locator = st.locator === undefined ? "" : `${md ? " " : "  "}‹${code(st.locator)}›`;
+            put(lead, `${md ? `**${st.action}**` : st.action}${locator}${target}${anchors === "" ? "" : `  ${anchors}`}`, md ? 0 : prefixLen);
+            const sub = md ? "   - " : " ".repeat(prefixLen);
+            const subHang = sub.length + 2;
+            if (st.checks !== undefined) {
+                const joined = st.checks.map((k) => (k.weak ? `⚠ ${k.text} (proves nothing)` : `✓ ${k.text}`));
+                if (md)
+                    for (const j of joined)
+                        put(sub, j);
+                else if (sub.length + joined.join(" · ").length <= width)
+                    put(sub, joined.join(" · "), subHang);
+                else
+                    for (const j of joined)
+                        put(sub, j, subHang);
+            }
+            const writes = [...new Set(r.sideEffects.writeRequests.filter((w) => w.step === st.number && w.source !== "end-state").map((w) => `${w.method} ${w.endpoint}`))];
+            if (writes.length > 0)
+                put(sub, `writes ${writes.join(" · ")}`, subHang);
+            if (full) {
+                if (st.objective !== undefined)
+                    put(sub, `Objective: ${st.objective}`, subHang);
+                if (st.expectedResult !== undefined)
+                    put(sub, `Expected result: ${st.expectedResult}`, subHang);
+                if (st.file !== undefined)
+                    put(sub, `File: ${code(st.file)}`, subHang);
+                if (st.params.length > 0)
+                    put(sub, `Params: ${st.params.map(code).join(", ")}`, subHang);
+            }
+        }
+        gap();
     }
-    // #433: the catalog links (job, persona), then the pre-approval findings — before the approval line.
-    if (r.catalog !== undefined) {
-        const k = r.catalog;
-        const status = (st) => (st === "stale" ? "STALE — needs re-review" : st === "unknown" ? "UNKNOWN — not declared in the catalog" : st);
-        section(h2("Catalog"), "", ...(k.linked
-            ? [
-                li(k.job === undefined ? `Job: ${em("none")}` : `Job: ${code(k.job.id)} (${status(k.job.status)})${k.job.story === undefined ? "" : ` — ${k.job.story}`}`),
-                li(k.persona === undefined ? `Persona: ${em("none")}` : `Persona: ${code(k.persona.id)} (${status(k.persona.status)})`),
-                ...(k.unvetted.length === 0 ? [] : [li(`Unvetted: ${k.unvetted.join(", ")} — promote needs them approved, or --accept-unvetted "<reason>"`)]),
-                ...(k.needsReReview.length === 0 ? [] : [li(`NEEDS RE-REVIEW: ${k.needsReReview.join("; ")}`)]),
-            ]
-            : [li(em("not linked to a job/persona"))]));
+    // ── Proves at the end
+    const endState = r.proof.endStateText ?? r.proof.endState;
+    if (endState.length > 0) {
+        head("PROVES AT THE END", "Proves at the end");
+        for (const e of endState)
+            put(`${bullet}✓ `, e, bullet.length + 2);
+        gap();
     }
-    if (r.findings !== undefined)
-        section(...renderFindings(r.findings, style));
-    if (r.approval?.waivers !== undefined || r.approval?.acceptedFindings !== undefined) {
-        section(h3("Recorded with the last approval"), ...(r.approval.waivers ?? []).map((w) => li(`waived (${w.kind}): "${w.reason}" — ${w.items.join(", ")}`)), ...(r.approval.acceptedFindings === undefined ? [] : [li(`acknowledged findings: "${r.approval.acceptedFindings.reason}" — ${r.approval.acceptedFindings.findings.join(", ")}`)]));
+    // ── Writes
+    const fx = r.sideEffects;
+    const byEndpoint = new Map();
+    for (const w of fx.writeRequests) {
+        const key = `${w.method} ${w.endpoint}`;
+        const e = byEndpoint.get(key) ?? { steps: [], end: false };
+        if (w.step !== undefined)
+            e.steps.push(w.step);
+        if (w.source === "end-state")
+            e.end = true;
+        byEndpoint.set(key, e);
     }
+    if (byEndpoint.size > 0 || fx.riskyControls.length > 0 || fx.origins.length > 1) {
+        head("WRITES", "Writes");
+        for (const [key, e] of byEndpoint) {
+            const where = [...(e.steps.length === 0 ? [] : [`${e.steps.length > 1 ? "steps" : "step"} ${stepRanges(e.steps)}`]), ...(e.end ? ["end state"] : [])];
+            put(bullet, `${code(key)}${where.length === 0 ? "" : ` (${where.join(", ")})`}`);
+        }
+        for (const x of fx.riskyControls) {
+            put(bullet, `Risky control, step ${x.step}: ${x.role === undefined ? "" : `${x.role} `}"${x.control}" — ${x.risk} [${code(x.ruleId)}]${x.waivedBy === undefined ? "" : ` (exempted by allowControl ${code(x.waivedBy)})`}`);
+        }
+        if (fx.origins.length > 1)
+            put(bullet, `Origins: ${fx.origins.map(code).join(", ")}`);
+        gap();
+    }
+    // ── Clear
+    const clear = [];
+    const lint = r.proof.lint;
+    if (lint.errors === 0 && lint.warnings === 0)
+        clear.push("lint ✓");
+    if (r.locatorHealth !== undefined && r.locatorHealth.brittle === 0)
+        clear.push(`locators ${r.locatorHealth.stable}/${r.locatorHealth.stable} stable ✓`);
+    if (r.catalog !== undefined && !r.catalog.linked)
+        clear.push("not linked to a job/persona (info)");
+    else if (r.catalog !== undefined && r.catalog.unvetted.length === 0 && r.catalog.needsReReview.length === 0)
+        clear.push("catalog links ✓");
+    const related = new Set((r.findings ?? []).filter((f) => f.analyzer === "catalog-analysis" && f.code.startsWith("pair:")).flatMap((f) => (f.items ?? []).filter((i) => i !== `journey:${r.id}`)));
+    const relatedCount = related.size > 0 ? related.size : (r.findings ?? []).filter((f) => f.analyzer === "catalog-analysis" && f.code.startsWith("pair:")).length;
+    if (relatedCount > 0)
+        clear.push(`${plural(relatedCount, "related Journey", "related Journeys")} share writes${full ? "" : " (--full for detail)"}`);
+    const v = r.proof.verify;
+    if (v.status === "recorded" && !v.stale && v.verdict !== "insensitive")
+        clear.push(`mutation proof ${v.verdict} ✓`);
+    if (clear.length > 0) {
+        if (md)
+            out.push("## Clear", "", clear.join(" · "));
+        else
+            put("CLEAR    ", clear.join(" · "), 9);
+        gap();
+    }
+    // ── Self-heal proposal
     if (r.proposal !== undefined) {
         const pr = r.proposal;
+        head("PROPOSED REVISION (SELF-HEAL)", "Proposed revision (self-heal)");
+        put(bullet, `${code(pr.proposalId)} from ${humanTime(pr.createdAt)}: accepting it makes the content hash ${nb(code(pr.proposedHash))} (made against ${nb(code(pr.baseHash))})`);
         const scope = pr.changes.range ?? (pr.changes.notes.length > 0 ? "change notes" : "no change context");
-        section(h2("Proposed revision (self-heal)"), "", li(`Proposal ${code(pr.proposalId)} from ${pr.createdAt}, made against ${code(pr.baseHash)}; accepting it makes the content hash ${code(pr.proposedHash)}`), li(`Change context: ${scope}${pr.changes.baseSha === undefined ? "" : ` (${pr.changes.baseSha.slice(0, 8)}..${(pr.changes.headSha ?? "").slice(0, 8)})`}`), ...pr.changes.notes.map((n) => li(`note: ${n}`, 1)), li(`Heal attempts: ${pr.attempts.total} (${pr.attempts.rejected} rejected)`), ...(pr.stale ? [li(`STALE — the Journey changed after this proposal was made; it cannot be accepted. Re-run: jevitate journey run ${r.id} --self-heal`)] : []), ...(pr.problem !== undefined && !pr.stale ? [li(`REFUSED — ${pr.problem}`)] : []), "", ...pr.steps.flatMap((st) => [
-            `${md ? "" : "  "}${st.number}. ${md ? `**${st.hypothesis}**` : st.hypothesis}`,
-            `${md ? "   " : "     "}- Before: ${code(st.before)}`,
-            `${md ? "   " : "     "}- After: ${code(st.after)}`,
-            ...st.evidence.map((e) => `${md ? "   " : "     "}- Evidence: ${e}`),
-            ...st.screenshots.map((sh) => `${md ? "   " : "     "}- Screenshot: ${sh}`),
-        ]), "", pr.stale || pr.problem !== undefined ? em("not acceptable as it stands") : `Accept exactly this revision: ${code(pr.acceptCommand)}`, `Reject it: ${code(`jevitate journey promote ${r.id} --reject-proposal ${pr.proposalId} --reason "<why>"`)}`);
+        put(bullet, `Change context: ${scope}${pr.changes.baseSha === undefined ? "" : ` (${pr.changes.baseSha.slice(0, 8)}..${(pr.changes.headSha ?? "").slice(0, 8)})`} · heal attempts ${pr.attempts.total} (${pr.attempts.rejected} rejected)`);
+        for (const n of pr.changes.notes)
+            put(bullet, `note: ${n}`);
+        if (pr.stale)
+            put(bullet, `STALE — the Journey changed after this proposal was made; it cannot be accepted. Re-run: ${cmd(`jevitate journey run ${r.id} --self-heal`)}`);
+        if (pr.problem !== undefined && !pr.stale)
+            put(bullet, `REFUSED — ${pr.problem}`);
+        for (const st of pr.steps) {
+            put(bullet, `Step ${st.number}: ${st.hypothesis}`);
+            put(`${bullet}  `, `before: ${code(st.before)}`);
+            put(`${bullet}  `, `after:  ${code(st.after)}`);
+            for (const e of st.evidence)
+                put(`${bullet}  `, `evidence: ${e}`);
+            for (const sh of st.screenshots)
+                put(`${bullet}  `, `screenshot: ${sh}`);
+        }
+        if (pr.stale || pr.problem !== undefined)
+            put(bullet, em("not acceptable as it stands"));
+        else
+            put(bullet, `Accept exactly this revision: ${cmd(pr.acceptCommand)}`);
+        put(bullet, `Reject it: ${cmd(`jevitate journey promote ${r.id} --reject-proposal ${pr.proposalId} --reason "<why>"`)}`);
+        gap();
+    }
+    // ── Full detail
+    if (full) {
+        head("DETAIL", "Detail");
+        const h3 = (t) => {
+            out.push(md ? `### ${t}` : `${t}:`);
+        };
+        h3(`Lint: ${lint.errors} error(s), ${lint.warnings} warning(s)`);
+        if (lint.findings.length === 0)
+            put(bullet, em("no findings"));
+        for (const f of lint.findings)
+            put(bullet, `${f.level} ${f.rule}${f.step === undefined ? "" : ` (step ${f.step})`}: ${f.message}`);
+        if (r.proof.acceptedWeak !== undefined)
+            put(bullet, `Accepted weak: "${r.proof.acceptedWeak.reason}" (waived: ${r.proof.acceptedWeak.rules.join(", ")})`);
+        const verify = v.status === "not-verified" ? `not verified — ${v.hint}` : `${v.verdict} (${humanTime(v.at)})${v.stale ? " — STALE: the Journey changed after this proof ran" : ""}${v.reason === undefined ? "" : ` — ${v.reason}`}: ${Object.entries(v.summary).map(([k, n]) => `${n} ${k}`).join(", ")}`;
+        put("", `Mutation proof: ${verify}`);
+        gap();
+        h3("Change since last approval");
+        if (c.kind === "first-approval")
+            put(bullet, em("first approval — nothing approved before"));
+        else if (c.kind === "no-record")
+            put(bullet, em("promoted before approvals were recorded — no approved version to compare with"));
+        else {
+            put(bullet, `Approved${c.approvedAt === undefined ? "" : ` ${humanTime(c.approvedAt)}`} as ${nb(code(c.approvedHash))}${c.kind === "snapshot-missing" ? "; its snapshot is missing" : ""} — ${c.changed ? "CHANGED since" : "unchanged since"}`);
+            if (c.stepIdOnly === true)
+                put(bullet, STEP_ID_ONLY_LABEL);
+            if (c.kind === "diff") {
+                for (const [label, d] of [["Steps", c.steps], ["Assertions", c.assertions], ["Side effects", c.sideEffects]]) {
+                    if (d.added.length === 0 && d.removed.length === 0)
+                        continue;
+                    put(bullet, `${label}:`);
+                    for (const l of d.removed)
+                        put(`${bullet}  `, `− ${l}`, bullet.length + 4);
+                    for (const l of d.added)
+                        put(`${bullet}  `, `+ ${l}`, bullet.length + 4);
+                }
+            }
+        }
+        gap();
+        if (r.anchorWarnings !== undefined && r.anchorWarnings.length > 0) {
+            h3("Anchor rules");
+            for (const w of r.anchorWarnings)
+                put(bullet, `${w.severity} ${w.path}${w.step === undefined ? "" : ` (step ${w.step})`}: ${w.message}${w.fix === undefined ? "" : ` — fix: ${w.fix}`}`);
+            gap();
+        }
+        if (r.locatorHealth !== undefined) {
+            const lh = r.locatorHealth;
+            h3("Locator health (advisory)");
+            put("", lh.line);
+            if (lh.brittleSteps.length === 0)
+                put(bullet, em("no brittle steps"));
+            for (const b of lh.brittleSteps)
+                put(bullet, `step ${b.index + 1}${b.stepId === undefined ? "" : ` [${b.stepId}]`} ${b.kind} ${code(b.locator)}${b.route === undefined ? "" : ` on ${b.route}`} — ${b.reasons.join("; ")} — fix: ${b.fix}`);
+            gap();
+        }
+        if (r.catalog !== undefined) {
+            const k = r.catalog;
+            const st = (x) => (x === "stale" ? "STALE — needs re-review" : x === "unknown" ? "UNKNOWN — not declared in the catalog" : x);
+            h3("Catalog");
+            if (!k.linked)
+                put(bullet, em("not linked to a job/persona"));
+            else {
+                put(bullet, k.job === undefined ? "Job: none" : `Job: ${code(k.job.id)} (${st(k.job.status)})${k.job.story === undefined ? "" : ` — ${k.job.story}`}`);
+                put(bullet, k.persona === undefined ? "Persona: none" : `Persona: ${code(k.persona.id)} (${st(k.persona.status)})`);
+            }
+            gap();
+        }
+        if (r.findings !== undefined) {
+            for (const l of renderFindings(r.findings, style)) {
+                if (md || l === "" || !/^\s*- /.test(l))
+                    out.push(l);
+                else {
+                    const lead = /^(\s*- )/.exec(l)[1];
+                    put(lead, l.slice(lead.length), lead.length + 2);
+                }
+            }
+        }
+        if (r.approval !== undefined) {
+            h3("Approval record");
+            put(bullet, describeProvenance(prov));
+            for (const w of r.approval.waivers ?? [])
+                put(bullet, `waived (${w.kind}): "${w.reason}" — ${w.items.join(", ")}`);
+            if (r.approval.acceptedFindings !== undefined)
+                put(bullet, `acknowledged findings: "${r.approval.acceptedFindings.reason}" — ${r.approval.acceptedFindings.findings.join(", ")}`);
+            gap();
+        }
     }
-    section(h2("Content hash"), "", `Content hash: ${code(r.contentHash)}`, "", `Approve exactly this version: ${code(`jevitate journey promote ${r.id} --reviewed-hash ${r.contentHash}`)}`);
-    return `${out.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}\n`;
+    // ── Approve (the one place the content hash appears)
+    const approved = r.promoted && !changed && (c.kind === "diff" || c.kind === "snapshot-missing" || c.kind === "no-record");
+    head("APPROVE", "Approve");
+    const approveCmd = cmd(`jevitate journey promote ${r.id} --reviewed-hash ${r.contentHash}`);
+    put(bullet, `${approved ? "(already approved) " : ""}${approveCmd}`);
+    if (md)
+        out.push("", `Content hash: ${code(r.contentHash)}`);
+    else
+        out.push(`Content hash: ${r.contentHash}`);
+    return `${out.map((l) => paint(l, opts.color === true && !md)).join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}\n`;
 }
 /** #432: the review sheet as Markdown (`journey review --markdown`). */
-export function renderReviewMarkdown(review) {
-    return renderSheet(review, "markdown");
+export function renderReviewMarkdown(review, opts = {}) {
+    return renderSheet(review, "markdown", opts);
 }
 /** #432: the review sheet as plain text (`journey review`, and `journey promote` in human mode). */
-export function renderReviewText(review) {
-    return renderSheet(review, "text");
+export function renderReviewText(review, opts = {}) {
+    return renderSheet(review, "text", opts);
 }
 /** #432: a review sheet file's content hash refused (none, or two different ones). */
 export class ReviewSheetError extends Error {