humanish 0.111.4 → 0.112.0

package/dist/analysis/types.d.ts

@@ -104,6 +104,11 @@ export interface AnalysisObservation {
 interface AnalysisFinding {
     id: string;
     title: string;
+    /** One plain sentence for a reader who did not watch the session. Absent in older reports. */
+    headline?: string;
+    /** One to three plain sentences: what the person tried, what got in the way, how it seemed to
+     * feel. Absent in older reports. */
+    experience?: string;
     summary: string;
     impact: "blocked_task" | "friction" | "recovery" | "uncertain";
     affectedStreamIds: string[];
@@ -115,6 +120,22 @@ interface AnalysisFinding {
     nextStep: string;
     priorityReason: string;
 }
+/** A problem a product designer would see in the cited captures, whether or not a participant
+ * mentioned it. It cites at least one capture. */
+interface AnalysisDesignFinding {
+    id: string;
+    headline: string;
+    /** The screen, in plain words. */
+    screen: string;
+    notice: string;
+    whyItMatters: string;
+    suggestion: string;
+    severity: "minor" | "moderate" | "major";
+    confidence: "low" | "medium" | "high";
+    /** Participants whose cited evidence shows the problem. */
+    seenByStreamIds: string[];
+    evidenceIds: string[];
+}
 /** Evidence-grounded disposition of a material concern, not model reasoning. */
 interface AnalysisConcernReview extends AnalysisObservation {
     disposition: "finding" | "context" | "unsupported";
@@ -128,6 +149,8 @@ export interface AnalysisResult {
     concernReviews?: AnalysisConcernReview[];
     /** Highest priority first; counts are derived from distinct stream sets. */
     findings: AnalysisFinding[];
+    /** Absent in older reports. New analyses supply it, empty when the captures show no problem. */
+    designFindings?: AnalysisDesignFinding[];
     limitations: string[];
 }
 interface OpenAIAnalysisConfig {

package/dist/analysis/validation.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { type AnalysisArtifact, type AnalysisCorrection, type AnalysisInput, type AnalysisResult } from "./types.js";
-/** Historical artifacts may omit concernReviews; every new provider response must supply it. */
+/** Historical artifacts may omit concernReviews, headlines, experiences and designFindings; every
+ * new provider response must supply them. */
 export declare const analysisResponseSchema: z.ZodObject<{
     summary: z.ZodString;
     participants: z.ZodArray<z.ZodObject<{
@@ -22,9 +23,30 @@ export declare const analysisResponseSchema: z.ZodObject<{
         }, z.core.$strict>>;
         limitations: z.ZodArray<z.ZodString>;
     }, z.core.$strict>>;
+    concernReviews: z.ZodNonOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        claim: z.ZodString;
+        basis: z.ZodEnum<{
+            action: "action";
+            inference: "inference";
+            participant_statement: "participant_statement";
+            visual: "visual";
+        }>;
+        evidenceIds: z.ZodArray<z.ZodString>;
+        limitation: z.ZodString;
+        disposition: z.ZodEnum<{
+            context: "context";
+            finding: "finding";
+            unsupported: "unsupported";
+        }>;
+        findingId: z.ZodNullable<z.ZodString>;
+        reason: z.ZodString;
+    }, z.core.$strict>>>>;
+    limitations: z.ZodArray<z.ZodString>;
     findings: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         title: z.ZodString;
+        headline: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
+        experience: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
         summary: z.ZodString;
         impact: z.ZodEnum<{
             blocked_task: "blocked_task";
@@ -59,25 +81,26 @@ export declare const analysisResponseSchema: z.ZodObject<{
         nextStep: z.ZodString;
         priorityReason: z.ZodString;
     }, z.core.$strict>>;
-    concernReviews: z.ZodNonOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
-        claim: z.ZodString;
-        basis: z.ZodEnum<{
-            action: "action";
-            inference: "inference";
-            participant_statement: "participant_statement";
-            visual: "visual";
+    designFindings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        headline: z.ZodString;
+        screen: z.ZodString;
+        notice: z.ZodString;
+        whyItMatters: z.ZodString;
+        suggestion: z.ZodString;
+        severity: z.ZodEnum<{
+            major: "major";
+            minor: "minor";
+            moderate: "moderate";
         }>;
-        evidenceIds: z.ZodArray<z.ZodString>;
-        limitation: z.ZodString;
-        disposition: z.ZodEnum<{
-            context: "context";
-            finding: "finding";
-            unsupported: "unsupported";
+        confidence: z.ZodEnum<{
+            high: "high";
+            low: "low";
+            medium: "medium";
         }>;
-        findingId: z.ZodNullable<z.ZodString>;
-        reason: z.ZodString;
-    }, z.core.$strict>>>>;
-    limitations: z.ZodArray<z.ZodString>;
+        seenByStreamIds: z.ZodArray<z.ZodString>;
+        evidenceIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const analysisResultJsonSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
     summary: z.ZodString;
@@ -100,9 +123,30 @@ export declare const analysisResultJsonSchema: z.core.ZodStandardJSONSchemaPaylo
         }, z.core.$strict>>;
         limitations: z.ZodArray<z.ZodString>;
     }, z.core.$strict>>;
+    concernReviews: z.ZodNonOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        claim: z.ZodString;
+        basis: z.ZodEnum<{
+            action: "action";
+            inference: "inference";
+            participant_statement: "participant_statement";
+            visual: "visual";
+        }>;
+        evidenceIds: z.ZodArray<z.ZodString>;
+        limitation: z.ZodString;
+        disposition: z.ZodEnum<{
+            context: "context";
+            finding: "finding";
+            unsupported: "unsupported";
+        }>;
+        findingId: z.ZodNullable<z.ZodString>;
+        reason: z.ZodString;
+    }, z.core.$strict>>>>;
+    limitations: z.ZodArray<z.ZodString>;
     findings: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         title: z.ZodString;
+        headline: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
+        experience: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
         summary: z.ZodString;
         impact: z.ZodEnum<{
             blocked_task: "blocked_task";
@@ -137,25 +181,26 @@ export declare const analysisResultJsonSchema: z.core.ZodStandardJSONSchemaPaylo
         nextStep: z.ZodString;
         priorityReason: z.ZodString;
     }, z.core.$strict>>;
-    concernReviews: z.ZodNonOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
-        claim: z.ZodString;
-        basis: z.ZodEnum<{
-            action: "action";
-            inference: "inference";
-            participant_statement: "participant_statement";
-            visual: "visual";
+    designFindings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        headline: z.ZodString;
+        screen: z.ZodString;
+        notice: z.ZodString;
+        whyItMatters: z.ZodString;
+        suggestion: z.ZodString;
+        severity: z.ZodEnum<{
+            major: "major";
+            minor: "minor";
+            moderate: "moderate";
         }>;
-        evidenceIds: z.ZodArray<z.ZodString>;
-        limitation: z.ZodString;
-        disposition: z.ZodEnum<{
-            context: "context";
-            finding: "finding";
-            unsupported: "unsupported";
+        confidence: z.ZodEnum<{
+            high: "high";
+            low: "low";
+            medium: "medium";
         }>;
-        findingId: z.ZodNullable<z.ZodString>;
-        reason: z.ZodString;
-    }, z.core.$strict>>>>;
-    limitations: z.ZodArray<z.ZodString>;
+        seenByStreamIds: z.ZodArray<z.ZodString>;
+        evidenceIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strict>>;
 /** Stable hashing is independent of object insertion order and excludes no fields implicitly. */
 export declare function hashAnalysisValue(value: unknown): string;

package/dist/analysis/validation.js

@@ -27,6 +27,20 @@ const observationSchema = z
     limitation: text(2000),
 })
     .strict();
+const designFindingSchema = z
+    .object({
+    id,
+    headline: label,
+    screen: label,
+    notice: text(1500).min(1),
+    whyItMatters: text(1000).min(1),
+    suggestion: text(1000).min(1),
+    severity: z.enum(["minor", "moderate", "major"]),
+    confidence: z.enum(["low", "medium", "high"]),
+    seenByStreamIds: sourceIds.min(1),
+    evidenceIds: refs,
+})
+    .strict();
 const analysisResultSchema = z
     .object({
     summary: text(4000).min(1),
@@ -51,6 +65,8 @@ const analysisResultSchema = z
         .object({
         id,
         title: label,
+        headline: label.optional(),
+        experience: text(1200).min(1).optional(),
         summary: text(4000).min(1),
         impact: z.enum(["blocked_task", "friction", "recovery", "uncertain"]),
         affectedStreamIds: sourceIds.min(1),
@@ -64,6 +80,7 @@ const analysisResultSchema = z
     })
         .strict())
         .max(100),
+    designFindings: z.array(designFindingSchema).max(40).optional(),
     concernReviews: z
         .array(observationSchema
         .extend({
@@ -77,13 +94,25 @@ const analysisResultSchema = z
     limitations,
 })
     .strict();
-/** Historical artifacts may omit concernReviews; every new provider response must supply it. */
-export const analysisResponseSchema = analysisResultSchema.required({
-    concernReviews: true,
-});
+/** Historical artifacts may omit concernReviews, headlines, experiences and designFindings; every
+ * new provider response must supply them. */
+export const analysisResponseSchema = analysisResultSchema
+    .extend({
+    findings: z
+        .array(analysisResultSchema.shape.findings.element.required({ headline: true, experience: true }))
+        .max(100),
+    designFindings: z.array(designFindingSchema).max(40),
+})
+    .required({ concernReviews: true });
 export const analysisResultJsonSchema = z.toJSONSchema(analysisResponseSchema);
-const normalizedResult = ({ concernReviews, ...result }) => ({
+const normalizedResult = ({ concernReviews, designFindings, findings, ...result }) => ({
     ...result,
+    findings: findings.map(({ headline, experience, ...finding }) => ({
+        ...finding,
+        ...(headline === undefined ? {} : { headline }),
+        ...(experience === undefined ? {} : { experience }),
+    })),
+    ...(designFindings === undefined ? {} : { designFindings }),
     ...(concernReviews === undefined ? {} : { concernReviews }),
 });
 const analysisCoverageSchema = z
@@ -349,6 +378,21 @@ export function checkAnalysisResult(input, value) {
         if (finding.affectedStreamIds.some((stream) => !citedStreams.has(stream)))
             errors.add("ANALYSIS_AFFECTED_WITHOUT_EVIDENCE");
     }
+    const designFindings = result.designFindings ?? [];
+    if (!distinct(designFindings.map((finding) => finding.id)))
+        errors.add("ANALYSIS_DESIGN_FINDING_ID_DUPLICATE");
+    for (const finding of designFindings) {
+        const refs = finding.evidenceIds.map((ref) => evidence.get(ref));
+        if (!distinct(finding.evidenceIds) || refs.some((ref) => !ref || !included.has(ref.streamId)))
+            errors.add("ANALYSIS_DESIGN_REFERENCE_INVALID");
+        if (!refs.some((ref) => ref?.capture !== null && ref?.capture !== undefined))
+            errors.add("ANALYSIS_DESIGN_WITHOUT_CAPTURE");
+        // Seen by means a cited capture of that participant shows the problem.
+        const captured = new Set(refs.flatMap((ref) => (ref?.capture ? [ref.streamId] : [])));
+        if (!distinct(finding.seenByStreamIds) ||
+            finding.seenByStreamIds.some((stream) => !included.has(stream) || !captured.has(stream)))
+            errors.add("ANALYSIS_DESIGN_MEMBERSHIP_INVALID");
+    }
     for (const review of result.concernReviews ?? []) {
         const citedStreams = checkObservation(review);
         const finding = result.findings.find((item) => item.id === review.findingId);
@@ -425,12 +469,15 @@ export function validateAnalysisArtifact(value) {
         (artifact.status === "complete" && !coverage.complete))
         throw new Error("ANALYSIS_STATUS_INVALID");
     if (artifact.result !== null) {
-        // Concern accounting became required with revision 5. Keep the boundary stable
-        // when the prompt version advances; a later prompt must not regain legacy omissions.
-        const revision = /^study-evidence-(\d+)$/.exec(artifact.promptVersion)?.[1];
-        if (revision !== undefined &&
-            Number(revision) >= 5 &&
-            artifact.result.concernReviews === undefined)
+        // Concern accounting became required with revision 5, and headlines, experiences and design
+        // findings with revision 7. Keep each boundary stable when the prompt version advances; a later
+        // prompt must not regain legacy omissions.
+        const revision = Number(/^study-evidence-(\d+)$/.exec(artifact.promptVersion)?.[1] ?? 0);
+        const result = artifact.result;
+        if ((revision >= 5 && result.concernReviews === undefined) ||
+            (revision >= 7 &&
+                (result.designFindings === undefined ||
+                    result.findings.some((finding) => finding.headline === undefined || finding.experience === undefined))))
             throw new Error("ANALYSIS_RESULT_SCHEMA_INVALID");
         validateAnalysisResult({ ...artifact, images: [] }, artifact.result);
     }

package/dist/cli/commands/runs.js

@@ -6,6 +6,7 @@ import { DEFAULT_EXPORT_MAX_BYTES, exportRun, formatExportHuman } from "../../fe
 import { listRuns, readReview } from "../../run/stored-runs.js";
 import { verifyRun } from "../../verify/verify.js";
 import { reclaimPreflightSandboxes, reclaimRunSandboxes, } from "../../run/reclaim.js";
+import { runDisplay } from "../../run/display.js";
 import { addRunOptions, handleRun } from "./run-command.js";
 import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, RUN_OPTION_DESCRIPTION, writeResult, humanError, } from "../io.js";
 import { plural } from "../../run/text.js";
@@ -33,7 +34,7 @@ export function registerVerifyCommand(parent, io) {
         io.setExitCode(result.ok ? 0 : 2);
     });
 }
-const CLEANUP_RENAMED = "`cleanup` is now `reclaim --check`; `cleanup` is removed in 0.112.0.";
+const CLEANUP_RENAMED = "`cleanup` is now `reclaim --check`; `cleanup` is removed in the first minor release on or after 2026-11-03.";
 /**
  * The deprecated `cleanup`, hidden from help: one warning, then exactly `reclaim --check`, with
  * its output and exit code. The old command read only what computer-use runs recorded and passed
@@ -244,13 +245,6 @@ const REVIEW_VERDICTS = {
     blocked: "blocked",
     timed_out: "timed out",
 };
-/** The state runDisplay gives a finished run whose own ok agrees with its verdict. */
-const VERDICT_STATES = {
-    pass: "passed",
-    fail: "failed",
-    blocked: "blocked",
-    timed_out: "timed_out",
-};
 /**
  * Review's headline: the run's display label, as `humanish runs`, review.md and the Observer show
  * it. A verdict that names another state follows in parentheses, so an interrupted run whose last
@@ -262,8 +256,8 @@ function reviewHeadline(verdict, display) {
         return REVIEW_VERDICTS[verdict];
     if (display.state === "no_verdict" || display.state === "dry_run")
         return `${display.label}; ${NOTHING_TESTED}`;
-    const judged = VERDICT_STATES[verdict];
-    return judged === undefined || judged === display.state
+    const judged = runDisplay({ liveness: "finished", verdict }).state;
+    return verdict === "contract_proof_only" || judged === display.state
         ? display.label
         : `${display.label} (verdict ${REVIEW_VERDICTS[verdict]})`;
 }

package/dist/cli/findings.d.ts

@@ -4,14 +4,13 @@ import type { AnalysisArtifact, LoadedAnalysis } from "../analysis/types.js";
 import { type CliIo } from "./io.js";
 export declare const ANALYSIS_FINDINGS_SCHEMA = "humanish.analysis-findings.v1";
 type Finding = NonNullable<AnalysisArtifact["result"]>["findings"][number];
+type DesignFinding = NonNullable<NonNullable<AnalysisArtifact["result"]>["designFindings"]>[number];
 /** `ready` and `stale` carry findings; every other state carries none and says why in `message`. */
 type FindingsState = "ready" | "stale" | "running" | "none" | "skipped" | "failed" | "dry_run" | "unavailable";
-interface FindingEvidence {
+interface CitedEvidence {
     id: string;
     streamId: string;
     kind: string;
-    /** How the finding's observations used this item: visual, action, participant_statement, inference. */
-    bases: string[];
     /** Index of the latest retained capture at this item, from 0; null before any capture. */
     frame: number | null;
     /** Time since the first retained capture, not a video offset. */
@@ -20,8 +19,19 @@ interface FindingEvidence {
     /** The capture file relative to the project directory, or null for nonvisual evidence. */
     capture: string | null;
 }
+interface FindingEvidence extends CitedEvidence {
+    /** How the finding's observations used this item: visual, action, participant_statement, inference. */
+    bases: string[];
+}
 interface FindingView {
     id: string;
+    /**
+     * One plain sentence about what happened, and one to three about what the person tried and what
+     * got in the way. Null in analyses written before them. An amended finding keeps the original
+     * text here; `correction.replacementClaim` replaces both.
+     */
+    headline: string | null;
+    experience: string | null;
     title: string;
     summary: string;
     impact: Finding["impact"];
@@ -41,6 +51,22 @@ interface FindingView {
         replacementClaim: string | null;
     } | null;
 }
+interface DesignFindingView {
+    id: string;
+    headline: string;
+    screen: string;
+    notice: string;
+    whyItMatters: string;
+    suggestion: string;
+    severity: DesignFinding["severity"];
+    confidence: DesignFinding["confidence"];
+    seenBy: {
+        streamId: string;
+        label: string;
+    }[];
+    /** Each cited item once; at least one has a capture. */
+    evidence: CitedEvidence[];
+}
 export interface AnalysisFindings {
     schema: typeof ANALYSIS_FINDINGS_SCHEMA;
     runId: string;
@@ -66,6 +92,11 @@ export interface AnalysisFindings {
     summary: string | null;
     /** Highest priority first, as the analysis ranked them. */
     findings: FindingView[];
+    /**
+     * Problems a designer would see in the captures, most severe first. Null when the view carries
+     * no analysis result, or the analysis was written before design findings.
+     */
+    designFindings: DesignFindingView[] | null;
     limitations: string[];
     warnings: string[];
 }

package/dist/cli/findings.js

@@ -27,16 +27,10 @@ function analyzeCommand(source, provider) {
         ? `${run} --provider codex`
         : `${run} --max-cost ${DEFAULT_ANALYSIS_MAX_COST_USD}`;
 }
-function evidenceOf(finding, analysis, runRoot) {
-    const bases = new Map();
-    for (const observation of finding.observations)
-        for (const id of observation.evidenceIds) {
-            const set = bases.get(id) ?? new Set();
-            set.add(observation.basis);
-            bases.set(id, set);
-        }
+/** The cited items the analysis evidence resolves, each once, in citation order. */
+function citedEvidence(ids, analysis, runRoot) {
     const byId = new Map(analysis.evidence.map((entry) => [entry.id, entry]));
-    return [...bases].flatMap(([id, used]) => {
+    return [...new Set(ids)].flatMap((id) => {
         const entry = byId.get(id);
         if (!entry)
             return [];
@@ -45,7 +39,6 @@ function evidenceOf(finding, analysis, runRoot) {
                 id,
                 streamId: entry.streamId,
                 kind: entry.kind,
-                bases: [...used],
                 frame: entry.frame,
                 elapsedMs: entry.elapsedMs,
                 at: entry.at,
@@ -54,11 +47,58 @@ function evidenceOf(finding, analysis, runRoot) {
         ];
     });
 }
+function evidenceOf(finding, analysis, runRoot) {
+    const bases = new Map();
+    for (const observation of finding.observations)
+        for (const id of observation.evidenceIds) {
+            const set = bases.get(id) ?? new Set();
+            set.add(observation.basis);
+            bases.set(id, set);
+        }
+    return citedEvidence(bases.keys(), analysis, runRoot).map(({ id, streamId, kind, ...entry }) => ({
+        id,
+        streamId,
+        kind,
+        bases: [...bases.get(id)],
+        ...entry,
+    }));
+}
+const SEVERITY_RANK = {
+    major: 0,
+    moderate: 1,
+    minor: 2,
+};
+/** Most severe first; equal severity keeps the analysis order. */
+function designFindingViews(analysis, runRoot) {
+    const designFindings = analysis.result?.designFindings;
+    if (designFindings === undefined)
+        return null;
+    const labels = new Map(analysis.participants.map((p) => [p.streamId, p.label]));
+    return [...designFindings]
+        .sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity])
+        .map((finding) => ({
+        id: finding.id,
+        headline: finding.headline,
+        screen: finding.screen,
+        notice: finding.notice,
+        whyItMatters: finding.whyItMatters,
+        suggestion: finding.suggestion,
+        severity: finding.severity,
+        confidence: finding.confidence,
+        seenBy: finding.seenByStreamIds.map((streamId) => ({
+            streamId,
+            label: labels.get(streamId) ?? streamId,
+        })),
+        evidence: citedEvidence(finding.evidenceIds, analysis, runRoot),
+    }));
+}
 function findingView(finding, loaded, runRoot) {
     const labels = new Map(loaded.analysis.participants.map((p) => [p.streamId, p.label]));
     const correction = loaded.corrections.filter((entry) => entry.findingId === finding.id).at(-1);
     return {
         id: finding.id,
+        headline: finding.headline ?? null,
+        experience: finding.experience ?? null,
         title: finding.title,
         summary: finding.summary,
         impact: finding.impact,
@@ -99,6 +139,7 @@ function withoutFindings(source, state, reason, message, next) {
         path: null,
         summary: null,
         findings: [],
+        designFindings: null,
         limitations: [],
         warnings: source.loaded.warnings,
     };
@@ -142,6 +183,7 @@ export function analysisFindings(source) {
             path: path.join(source.runRoot, "analysis", analysis.id, "analysis.json"),
             summary: result.summary,
             findings: result.findings.map((finding) => findingView(finding, { ...loaded, analysis }, source.runRoot)),
+            designFindings: designFindingViews(analysis, source.runRoot),
             limitations: result.limitations,
             warnings: loaded.warnings,
         };
@@ -288,20 +330,49 @@ function momentsText(evidence) {
         parts.push(`${plural(unframed, "item")} with no frame`);
     return parts.join(", ");
 }
+/** The capture files, relative to the run directory, in frame order. */
+function captureFiles(evidence, runRoot) {
+    return [
+        ...new Set(evidence
+            .filter((entry) => entry.capture !== null)
+            .sort((a, b) => (a.frame ?? 0) - (b.frame ?? 0))
+            .map((entry) => (runRoot ? path.relative(runRoot, entry.capture) : entry.capture))),
+    ];
+}
+/**
+ * What a reader sees first: the headline, or the reviewer's claim when a review amended the finding,
+ * since the headline and experience describe the claim it replaced. Null before headlines existed.
+ */
+function leadOf(finding) {
+    const amended = finding.correction?.status === "amended" ? finding.correction : null;
+    if (finding.headline === null)
+        return null;
+    return amended?.replacementClaim
+        ? { headline: amended.replacementClaim, corrected: true }
+        : { headline: finding.headline, corrected: false };
+}
 function findingLines(finding, runRoot) {
     const cited = [...new Set(finding.evidence.map((entry) => entry.streamId))];
     const labels = new Map(finding.affected.map((p) => [p.streamId, p.label]));
     const affectedIds = finding.affected.map((p) => p.streamId);
     const streams = [...affectedIds, ...cited.filter((id) => !labels.has(id))];
-    const captures = [
-        ...new Set(finding.evidence
-            .filter((entry) => entry.capture !== null)
-            .sort((a, b) => (a.frame ?? 0) - (b.frame ?? 0))
-            .map((entry) => (runRoot ? path.relative(runRoot, entry.capture) : entry.capture))),
-    ];
+    const captures = captureFiles(finding.evidence, runRoot);
     const correction = finding.correction;
+    const lead = leadOf(finding);
     return [
-        `${finding.id} ${finding.title}`,
+        ...(lead === null
+            ? [`${finding.id} ${finding.title}`]
+            : [
+                `${finding.id} ${lead.headline}`,
+                ...(lead.corrected
+                    ? [
+                        "   Corrected in human review. The reviewer's claim replaces the original headline and account.",
+                    ]
+                    : finding.experience === null
+                        ? []
+                        : [`   ${finding.experience}`]),
+                `   evidence: ${finding.title}`,
+            ]),
         `   impact: ${IMPACT_TEXT[finding.impact]} · confidence: ${finding.confidence} · recovery: ${RECOVERY_TEXT[finding.recovery]}`,
         `   ${finding.summary}`,
         `   affected: ${finding.affected.length} of ${plural(finding.exposedCount, "exposed participant")}`,
@@ -319,6 +390,34 @@ function findingLines(finding, runRoot) {
             ]),
     ];
 }
+function designFindingLines(finding, runRoot) {
+    const captures = captureFiles(finding.evidence, runRoot);
+    return [
+        `${finding.id} ${finding.severity}: ${finding.headline}`,
+        `   screen: ${finding.screen}`,
+        `   notice: ${finding.notice}`,
+        `   why it matters: ${finding.whyItMatters}`,
+        `   suggestion: ${finding.suggestion}`,
+        `   seen by: ${finding.seenBy.map((p) => p.label).join(", ")} · confidence: ${finding.confidence}`,
+        ...(captures.length === 0 ? [] : [`   captures: ${captures.join(", ")}`]),
+    ];
+}
+/** Nothing for an analysis written before design findings. */
+function designSection(view) {
+    const design = view.designFindings;
+    if (design === null)
+        return [];
+    if (design.length === 0)
+        return ["", "design findings: none in the reviewed captures"];
+    return [
+        "",
+        `design findings: ${design.length}, most severe first`,
+        ...design.flatMap((finding, index) => [
+            ...(index === 0 ? [] : [""]),
+            ...designFindingLines(finding, view.runPath ?? ""),
+        ]),
+    ];
+}
 /** The full findings block: the analysis, every finding with its evidence, and its limitations. */
 export function formatFindings(view) {
     if (view.state !== "ready" && view.state !== "stale")
@@ -330,6 +429,7 @@ export function formatFindings(view) {
         ...(view.state === "stale" ? [`warning: ${view.message}`, `next: ${view.next}`] : []),
         ...(view.summary ? [view.summary] : []),
         ...view.findings.flatMap((finding) => ["", ...findingLines(finding, view.runPath ?? "")]),
+        ...designSection(view),
         ...(view.limitations.length === 0
             ? []
             : ["", "limitations:", ...view.limitations.map((limitation) => `- ${limitation}`)]),
@@ -343,12 +443,30 @@ export function formatFindingsSummary(view, fullCommand, limit = 3) {
     if (view.state !== "ready" && view.state !== "stale")
         return [`findings: ${view.message}`, ...(view.next ? [`next: ${view.next}`] : [])];
     const shown = view.findings.slice(0, limit);
+    const design = view.designFindings;
     return [
         `findings: ${view.findings.length === 0 ? "none" : view.findings.length}${view.state === "stale" ? " (stale)" : ""}`,
-        ...shown.map((finding) => `- ${finding.id} ${IMPACT_TEXT[finding.impact]}, ${finding.confidence} confidence, ${RECOVERY_TEXT[finding.recovery]}: ${finding.title}`),
+        ...shown.map((finding) => {
+            const qualities = `${IMPACT_TEXT[finding.impact]}, ${finding.confidence} confidence, ${RECOVERY_TEXT[finding.recovery]}`;
+            const lead = leadOf(finding);
+            if (lead === null)
+                return `- ${finding.id} ${qualities}: ${finding.title}`;
+            return `- ${finding.id} ${lead.headline} (${lead.corrected ? "corrected in human review" : qualities})`;
+        }),
         ...(view.findings.length > limit
             ? [`- and ${plural(view.findings.length - limit, "more finding")}`]
             : []),
+        ...(design === null
+            ? []
+            : [
+                `design findings: ${design.length === 0 ? "none" : design.length}`,
+                ...design
+                    .slice(0, limit)
+                    .map((finding) => `- ${finding.id} ${finding.severity}: ${finding.headline}`),
+                ...(design.length > limit
+                    ? [`- and ${plural(design.length - limit, "more design finding")}`]
+                    : []),
+            ]),
         `all findings: ${fullCommand}`,
     ];
 }

package/dist/cli/io.d.ts

@@ -18,7 +18,8 @@ export declare const DOTENV_OPTION_DESCRIPTION = "Load unset variables from this
  * The hidden `--env-file <path>` that `--dotenv` replaced. Node scans the whole argv for
  * `--env-file` before a script runs, and stops only at `--` (src/node_dotenv.cc), so a missing file
  * exits 9 through Node and never reaches humanish. `--dotenv` does not collide.
- * Removed in 0.112.0: deprecated in 0.110.0 on 2026-10-03, it stays 30 days and one minor release.
+ * Removed in the first minor release on or after 2026-11-03: deprecated in 0.110.0 on 2026-10-03, it stays at least 30 days and one
+ * minor release.
  */
 export declare function envFileAliasOption(): Option;
 /** The dotenv path a command was given: `--dotenv`, or the `--env-file` alias with its warning. */