@opengeni/react 0.57.0 → 1.0.2-canary.37191796234001

package/src/components/human-input-form.tsx

@@ -1,12 +1,14 @@
 import type {
   HumanInputAnswer,
   HumanInputQuestion,
+  SkillRecord,
   SessionHumanInputRequest,
   SubmitHumanInputResponseRequest,
 } from "@opengeni/sdk";
 import { ChevronDownIcon, ChevronUpIcon, MessageCircleQuestionIcon } from "lucide-react";
 import { useEffect, useId, useRef, useState, type FormEvent, type ReactNode } from "react";
 import { cn } from "../lib/cn";
+import { useErrorMessage } from "../lib/error-message";
 
 export type HumanInputAnswerDraft = {
   values: string[];
@@ -14,6 +16,8 @@ export type HumanInputAnswerDraft = {
   otherSelected: boolean;
 };
 
+class SkillReviewVerificationError extends Error {}
+
 export type HumanInputFormMessages = {
   title: string;
   description: string;
@@ -40,7 +44,7 @@ export const defaultHumanInputFormMessages: HumanInputFormMessages = {
   title: "Input required",
   /** Multi-question chrome has no default subtitle; hosts may still override. */
   description: "",
-  submit: "Continue",
+  submit: "Send answers",
   skip: "Skip",
   submitting: "Submitting…",
   other: "Other",
@@ -64,6 +68,10 @@ export const defaultHumanInputFormMessages: HumanInputFormMessages = {
 };
 
 export type HumanInputFormProps = {
+  /** Scoped immutable revision reader. Saving a Skill fails closed without its full preview. */
+  loadSkillReview?:
+    | ((reference: NonNullable<HumanInputQuestion["skillReview"]>) => Promise<SkillRecord>)
+    | undefined;
   request: Pick<SessionHumanInputRequest, "id" | "questions" | "allowSkip" | "expiresAt">;
   onSubmit: (response: SubmitHumanInputResponseRequest) => void | Promise<void>;
   submitting?: boolean | undefined;
@@ -78,6 +86,12 @@ export type HumanInputFormProps = {
   autoFocus?: boolean | undefined;
   /** Start collapsed to a compact bar (drafts still retained). */
   defaultCollapsed?: boolean | undefined;
+  /**
+   * Answer a yes/no decision (one required choice between an accept and a
+   * decline option, without Other) with two buttons instead of a radio list.
+   * Off by default; embedded conversations turn it on.
+   */
+  decisionButtons?: boolean | undefined;
   className?: string | undefined;
 };
 
@@ -87,9 +101,18 @@ export type HumanInputFormProps = {
  * options, sticky ask/submit chrome. Hosts can replace title/description or
  * use `useHumanInputRequests` headlessly.
  */
-export function HumanInputForm({
+export function HumanInputForm(props: HumanInputFormProps) {
+  // The pending-request read model is refreshed after session events and
+  // returns newly allocated question arrays for the same durable request.
+  // Key the state owner by that request's lifecycle identity so reconciliation
+  // cannot erase an answer that the operator is still typing.
+  return <HumanInputRequestForm key={props.request.id} {...props} />;
+}
+
+function HumanInputRequestForm({
   request,
   onSubmit,
+  loadSkillReview,
   submitting = false,
   error,
   title,
@@ -100,10 +123,14 @@ export function HumanInputForm({
   messages: messageOverrides,
   autoFocus = true,
   defaultCollapsed = false,
+  decisionButtons = false,
   className,
 }: HumanInputFormProps) {
+  const formatError = useErrorMessage();
   const messages = { ...defaultHumanInputFormMessages, ...messageOverrides };
   const singleQuestion = request.questions.length === 1 ? request.questions[0]! : null;
+  const decision = decisionButtons ? binaryDecision(request.questions) : null;
+  const [decisionChoice, setDecisionChoice] = useState<string | null>(null);
   const resolvedTitle =
     title === undefined
       ? singleQuestion
@@ -134,16 +161,131 @@ export function HumanInputForm({
   const submissionInFlight = useRef(false);
   const submissionGeneration = useRef(0);
   const busy = submitting || submittingInternally;
-
+  const reviewIdentity = JSON.stringify(
+    request.questions
+      .filter((question) => question.skillReview)
+      .map((question) => ({
+        id: question.id,
+        reference: {
+          sourceOperationId: question.skillReview!.sourceOperationId,
+          skillId: question.skillReview!.skillId,
+          revisionId: question.skillReview!.revisionId,
+          expectedRevisionId: question.skillReview!.expectedRevisionId,
+          expectedScopeVersion: question.skillReview!.expectedScopeVersion,
+          ...(question.skillReview!.removalOperationId
+            ? { removalOperationId: question.skillReview!.removalOperationId }
+            : {}),
+        },
+      })),
+  );
+  const [reviewReload, setReviewReload] = useState(0);
+  const [reviews, setReviews] = useState<{
+    loader: typeof loadSkillReview;
+    identity: string;
+    records: Record<string, SkillRecord>;
+    error: string | null;
+  } | null>(null);
   useEffect(() => {
-    submissionGeneration.current += 1;
-    submissionInFlight.current = false;
-    setDrafts(initialDrafts(request.questions));
-    setValidationErrors({});
-    setSubmissionError(null);
-    setSubmittingInternally(false);
-    setCollapsed(defaultCollapsed);
-  }, [request.id, request.questions, defaultCollapsed]);
+    let current = true;
+    const questions = JSON.parse(reviewIdentity) as Array<{
+      id: string;
+      reference: NonNullable<HumanInputQuestion["skillReview"]>;
+    }>;
+    if (!questions.length) return;
+    setReviews(null);
+    void Promise.all(
+      questions.map(async (question) => {
+        if (!loadSkillReview)
+          throw new Error(
+            "This client cannot preview Skill files. Ask your administrator for a review-capable client.",
+          );
+        const reference = question.reference;
+        const record = await loadSkillReview(reference);
+        if (
+          record.id !== reference.skillId ||
+          record.revisionId !== reference.revisionId ||
+          (record.removalOperationId ?? undefined) !== reference.removalOperationId ||
+          !record.files.some((file) => file.path === "SKILL.md")
+        ) {
+          throw new SkillReviewVerificationError(
+            "The requested Skill revision could not be verified.",
+          );
+        }
+        return [question.id, record] as const;
+      }),
+    )
+      .then((records) => {
+        if (current)
+          setReviews({
+            loader: loadSkillReview,
+            identity: reviewIdentity,
+            records: Object.fromEntries(records),
+            error: null,
+          });
+      })
+      .catch((cause) => {
+        if (current)
+          setReviews({
+            loader: loadSkillReview,
+            identity: reviewIdentity,
+            records: {},
+            error: formatError(
+              cause,
+              cause instanceof SkillReviewVerificationError
+                ? cause.message
+                : !loadSkillReview
+                  ? "This client cannot preview Skill files. Ask your administrator for a review-capable client."
+                  : undefined,
+            ),
+          });
+      });
+    return () => {
+      current = false;
+    };
+  }, [loadSkillReview, reviewIdentity, reviewReload, formatError]);
+  const visibleReviews =
+    reviews?.loader === loadSkillReview && reviews?.identity === reviewIdentity ? reviews : null;
+  const preview = (question: HumanInputQuestion) => {
+    if (!question.skillReview) return null;
+    const record = visibleReviews?.records[question.id];
+    return (
+      <div className="mb-3 min-w-0 space-y-2" data-skill-review="">
+        {record ? (
+          <>
+            <p className="text-og-sm">
+              {record.title ?? "Skill"} · {record.scope} · {record.files.length} files
+            </p>
+            <p className="text-og-xs text-og-fg-muted">
+              {question.skillReview.removalOperationId
+                ? "Permanently deletes this Skill and all stored revisions. This cannot be undone; conversations remain unchanged."
+                : "Saving activates these exact files. No additional review is required."}
+            </p>
+            {record.files.map((file) => (
+              <details key={file.path} open={file.path === "SKILL.md"}>
+                <summary className="cursor-pointer break-all text-og-sm">{file.path}</summary>
+                <pre className="max-h-64 overflow-auto whitespace-pre-wrap break-words rounded-og-md bg-og-surface-1 p-2 text-og-xs">
+                  {file.content}
+                </pre>
+              </details>
+            ))}
+          </>
+        ) : visibleReviews?.error ? (
+          <>
+            <p role="alert" className="text-og-sm">
+              {visibleReviews.error}
+            </p>
+            <button type="button" onClick={() => setReviewReload((value) => value + 1)}>
+              Retry preview
+            </button>
+          </>
+        ) : (
+          <p role="status" className="text-og-sm">
+            Loading the exact Skill files…
+          </p>
+        )}
+      </div>
+    );
+  };
 
   useEffect(() => {
     if (collapsed) {
@@ -199,7 +341,7 @@ export function HumanInputForm({
       await onSubmit(response);
     } catch (cause) {
       if (generation === submissionGeneration.current) {
-        setSubmissionError(cause instanceof Error ? cause.message : String(cause));
+        setSubmissionError(formatError(cause));
       }
     } finally {
       if (generation === submissionGeneration.current) {
@@ -234,6 +376,22 @@ export function HumanInputForm({
       }
       return;
     }
+    const unreviewedSave = request.questions.find(
+      (question) =>
+        question.skillReview &&
+        !visibleReviews?.records[question.id] &&
+        result.answers.some(
+          (answer) => answer.questionId === question.id && answer.values.includes("save"),
+        ),
+    );
+    if (unreviewedSave) {
+      setValidationErrors({
+        [unreviewedSave.id]: unreviewedSave.skillReview?.removalOperationId
+          ? "Load the exact Skill proposal before approving permanent deletion."
+          : "Load the exact Skill files before saving.",
+      });
+      return;
+    }
     await submitResponse({ outcome: "answered", answers: result.answers });
   };
 
@@ -309,7 +467,7 @@ export function HumanInputForm({
             <div className="flex flex-wrap items-baseline gap-x-2 gap-y-0.5">
               <h2 id={titleId} className="text-og-md font-semibold text-og-fg">
                 {resolvedTitle}
-                {singleQuestion?.required && !request.allowSkip ? (
+                {singleQuestion?.required && !request.allowSkip && !decision ? (
                   <span aria-hidden className="ml-1 text-og-status-failed">
                     *
                   </span>
@@ -356,104 +514,245 @@ export function HumanInputForm({
         </div>
       </header>
 
-      <div className="relative flex min-h-0 flex-1 flex-col overflow-hidden">
-        <div
-          ref={scrollRef}
-          className="min-h-0 flex-1 overflow-y-auto overscroll-contain [scrollbar-gutter:stable]"
-        >
-          <fieldset disabled={busy} className="min-w-0 space-y-4 px-4 py-3">
-            {request.questions.map((question, index) => {
-              if (singleQuestion) {
-                // Title already carries the question; only render the control + help extras.
-                return (
-                  <div key={question.id} data-human-input-question={question.id}>
-                    <QuestionControls
-                      question={question}
-                      draft={drafts[question.id] ?? emptyDraft()}
-                      fieldId={`${formId}-${index}`}
-                      error={validationErrors[question.id]}
-                      messages={messages}
-                      autoFocus={autoFocus}
-                      firstOption
-                      showPromptChrome={false}
-                      allowSkip={request.allowSkip}
-                      busy={busy}
-                      onUpdate={(apply) => update(question.id, apply)}
-                    />
-                  </div>
-                );
-              }
+      {decision ? (
+        <>
+          {decision.question.helpText ||
+          decision.accept.description ||
+          decision.decline.description ? (
+            <div className="shrink-0 space-y-1 px-4 pt-3 text-og-sm text-og-fg-muted">
+              {decision.question.label && decision.question.helpText ? (
+                <p>{decision.question.helpText}</p>
+              ) : null}
+              {[decision.accept, decision.decline].map((option) =>
+                option.description ? (
+                  <p key={option.id}>
+                    <span className="font-medium text-og-fg">{option.label}</span>
+                    {" · "}
+                    {option.description}
+                  </p>
+                ) : null,
+              )}
+            </div>
+          ) : null}
+          {(error ?? submissionError) ? (
+            <p role="alert" className="shrink-0 px-4 pt-3 text-og-sm text-og-status-failed">
+              {error ?? submissionError}
+            </p>
+          ) : null}
+          <footer
+            className="flex shrink-0 flex-wrap items-center justify-end gap-2 px-4 py-3"
+            data-human-input-decision=""
+          >
+            {request.allowSkip ? (
+              <button
+                type="button"
+                disabled={busy}
+                onClick={() => void submitResponse({ outcome: "skipped" })}
+                className="mr-auto inline-flex min-h-9 items-center rounded-og-md px-2 py-1.5 text-og-sm font-medium text-og-fg-muted transition-colors hover:bg-og-hover hover:text-og-fg disabled:opacity-50 pointer-coarse:min-h-11"
+              >
+                {resolvedSkipLabel}
+              </button>
+            ) : null}
+            {[decision.decline, decision.accept].map((option) => {
+              const primary = option === decision.accept;
               return (
-                <div
-                  key={question.id}
-                  data-human-input-question={question.id}
-                  className="flex flex-col gap-1.5"
+                <button
+                  key={option.id}
+                  type="button"
+                  disabled={busy}
+                  ref={
+                    !primary && autoFocus
+                      ? (node) => {
+                          if (node && !node.dataset.ogFocused) {
+                            node.dataset.ogFocused = "";
+                            node.focus({ preventScroll: true });
+                          }
+                        }
+                      : undefined
+                  }
+                  data-human-input-choice={option.id}
+                  onClick={() => {
+                    setDecisionChoice(option.id);
+                    void submitResponse({
+                      outcome: "answered",
+                      answers: [{ questionId: decision.question.id, values: [option.id] }],
+                    });
+                  }}
+                  className={cn(
+                    "inline-flex min-h-9 items-center rounded-og-md border px-3.5 py-1.5 text-og-sm font-medium transition disabled:opacity-50 pointer-coarse:min-h-11",
+                    primary
+                      ? "border-og-primary-border bg-og-primary text-og-primary-fg hover:bg-og-primary-hover"
+                      : "border-og-border bg-og-surface-1 text-og-fg hover:bg-og-surface-2",
+                  )}
                 >
-                  <QuestionControls
-                    question={question}
-                    draft={drafts[question.id] ?? emptyDraft()}
-                    fieldId={`${formId}-${index}`}
-                    error={validationErrors[question.id]}
-                    messages={messages}
-                    autoFocus={autoFocus && index === 0}
-                    firstOption={index === 0}
-                    showPromptChrome
-                    allowSkip={request.allowSkip}
-                    busy={busy}
-                    onUpdate={(apply) => update(question.id, apply)}
-                  />
-                </div>
+                  {busy && decisionChoice === option.id ? messages.submitting : option.label}
+                </button>
               );
             })}
-          </fieldset>
-        </div>
-        {overflowBelow ? (
-          <div
-            className="pointer-events-none absolute inset-x-0 bottom-0 z-[1] flex flex-col items-center"
-            aria-hidden="true"
-          >
-            <div className="h-10 w-full bg-gradient-to-t from-og-surface-1 via-og-surface-1/85 to-transparent" />
-            <span className="-mt-5 mb-1 rounded-og-full bg-og-surface-1 px-2.5 py-0.5 text-og-xs font-medium text-og-fg-muted shadow-og-sm ring-1 ring-og-border/60">
-              {messages.moreBelow}
-            </span>
+          </footer>
+        </>
+      ) : (
+        <>
+          <div className="relative flex min-h-0 flex-1 flex-col overflow-hidden">
+            <div
+              ref={scrollRef}
+              className="min-h-0 flex-1 overflow-y-auto overscroll-contain [scrollbar-gutter:stable]"
+            >
+              <fieldset disabled={busy} className="min-w-0 space-y-4 px-4 py-3">
+                {request.questions.map((question, index) => {
+                  if (singleQuestion) {
+                    // Title already carries the question; only render the control + help extras.
+                    return (
+                      <div key={question.id} data-human-input-question={question.id}>
+                        {preview(question)}
+                        <QuestionControls
+                          question={question}
+                          questionNumber={null}
+                          labelledBy={titleId}
+                          draft={drafts[question.id] ?? emptyDraft()}
+                          fieldId={`${formId}-${index}`}
+                          error={validationErrors[question.id]}
+                          messages={messages}
+                          autoFocus={autoFocus}
+                          firstOption
+                          showPromptChrome={false}
+                          allowSkip={request.allowSkip}
+                          busy={busy}
+                          onUpdate={(apply) => update(question.id, apply)}
+                        />
+                      </div>
+                    );
+                  }
+                  return (
+                    <div
+                      key={question.id}
+                      data-human-input-question={question.id}
+                      className="flex flex-col gap-1.5"
+                    >
+                      {preview(question)}
+                      <QuestionControls
+                        question={question}
+                        questionNumber={index + 1}
+                        labelledBy={undefined}
+                        draft={drafts[question.id] ?? emptyDraft()}
+                        fieldId={`${formId}-${index}`}
+                        error={validationErrors[question.id]}
+                        messages={messages}
+                        autoFocus={autoFocus && index === 0}
+                        firstOption={index === 0}
+                        showPromptChrome
+                        allowSkip={request.allowSkip}
+                        busy={busy}
+                        onUpdate={(apply) => update(question.id, apply)}
+                      />
+                    </div>
+                  );
+                })}
+              </fieldset>
+            </div>
+            {overflowBelow ? (
+              <div
+                className="pointer-events-none absolute inset-x-0 bottom-0 z-[1] flex flex-col items-center"
+                aria-hidden="true"
+              >
+                <div className="h-10 w-full bg-gradient-to-t from-og-surface-1 via-og-surface-1/85 to-transparent" />
+                <span className="-mt-5 mb-1 rounded-og-full bg-og-surface-1 px-2.5 py-0.5 text-og-xs font-medium text-og-fg-muted shadow-og-sm ring-1 ring-og-border/60">
+                  {messages.moreBelow}
+                </span>
+              </div>
+            ) : null}
           </div>
-        ) : null}
-      </div>
 
-      {(error ?? submissionError) ? (
-        <p
-          role="alert"
-          className="relative z-10 shrink-0 px-4 pb-1 text-og-sm text-og-status-failed"
-        >
-          {error ?? submissionError}
-        </p>
-      ) : null}
+          {(error ?? submissionError) ? (
+            <p
+              role="alert"
+              className="relative z-10 shrink-0 px-4 pb-1 text-og-sm text-og-status-failed"
+            >
+              {error ?? submissionError}
+            </p>
+          ) : null}
 
-      <footer className="relative z-10 flex shrink-0 items-center justify-end gap-2 border-t border-og-status-waiting/20 bg-og-surface-1/95 px-4 py-3 backdrop-blur-[2px]">
-        {request.allowSkip ? (
-          <button
-            type="button"
-            disabled={busy}
-            onClick={() => void submitResponse({ outcome: "skipped" })}
-            className="inline-flex min-h-9 items-center rounded-og-md border border-og-border px-3 py-1.5 text-og-sm font-medium text-og-fg-muted transition-colors hover:bg-og-surface-1 hover:text-og-fg disabled:opacity-50"
-          >
-            {resolvedSkipLabel}
-          </button>
-        ) : null}
-        <button
-          type="submit"
-          disabled={busy}
-          className="inline-flex min-h-9 items-center rounded-og-md bg-og-accent px-3 py-1.5 text-og-sm font-medium text-og-accent-fg transition-colors hover:bg-og-accent-strong disabled:opacity-50"
-        >
-          {busy ? messages.submitting : resolvedSubmitLabel}
-        </button>
-      </footer>
+          <footer className="relative z-10 flex shrink-0 items-center justify-end gap-2 border-t border-og-status-waiting/20 bg-og-surface-1/95 px-4 py-3 backdrop-blur-[2px]">
+            {request.allowSkip ? (
+              <button
+                type="button"
+                disabled={busy}
+                onClick={() => void submitResponse({ outcome: "skipped" })}
+                className="inline-flex min-h-9 items-center rounded-og-md border border-og-border px-3 py-1.5 text-og-sm font-medium text-og-fg-muted transition-colors hover:bg-og-surface-1 hover:text-og-fg disabled:opacity-50"
+              >
+                {resolvedSkipLabel}
+              </button>
+            ) : null}
+            <button
+              type="submit"
+              disabled={busy}
+              className="inline-flex min-h-9 items-center rounded-og-md border border-og-primary-border bg-og-primary text-og-primary-fg px-3 py-1.5 text-og-sm font-medium transition hover:bg-og-primary-hover disabled:opacity-50"
+            >
+              {busy ? messages.submitting : resolvedSubmitLabel}
+            </button>
+          </footer>
+        </>
+      )}
     </form>
   );
 }
 
+// Unambiguous approve/decline verbs only: "Continue with A" vs "Keep B" is a
+// real choice between two options, not a yes/no decision.
+const ACCEPT_WORDS = new Set(["approve", "approved", "yes", "confirm", "allow", "accept"]);
+const DECLINE_WORDS = new Set(["cancel", "decline", "reject", "deny", "no", "don't", "dont"]);
+
+function firstWord(label: string): string {
+  return (
+    label
+      .trim()
+      .toLowerCase()
+      .replace(/[’]/g, "'")
+      .split(/[\s,.:;!?()]+/)[0] ?? ""
+  );
+}
+
+/**
+ * A yes/no decision (an approval asked as a question): one required
+ * single-choice question with exactly an accept and a decline option. It is
+ * answered with two buttons; an "Other" free-text answer has no meaning for it,
+ * and the composer still accepts a different instruction.
+ */
+export function binaryDecision(questions: readonly HumanInputQuestion[]): {
+  question: HumanInputQuestion;
+  accept: HumanInputQuestion["options"][number];
+  decline: HumanInputQuestion["options"][number];
+} | null {
+  if (questions.length !== 1) return null;
+  const question = questions[0]!;
+  if (
+    question.kind !== "single_select" ||
+    question.skillReview ||
+    // The runtime marks every choice question `allowOther`, so it is not a
+    // signal here; a different answer goes through the composer instead.
+    !question.required ||
+    question.options.length !== 2
+  )
+    return null;
+  const [first, second] = question.options as [
+    HumanInputQuestion["options"][number],
+    HumanInputQuestion["options"][number],
+  ];
+  const kind = (option: HumanInputQuestion["options"][number]) => {
+    const word = firstWord(option.label);
+    return ACCEPT_WORDS.has(word) ? "accept" : DECLINE_WORDS.has(word) ? "decline" : null;
+  };
+  const a = kind(first);
+  const b = kind(second);
+  if (a === "accept" && b === "decline") return { question, accept: first, decline: second };
+  if (a === "decline" && b === "accept") return { question, accept: second, decline: first };
+  return null;
+}
+
 function QuestionControls({
   question,
+  questionNumber,
+  labelledBy,
   draft,
   fieldId,
   error,
@@ -466,6 +765,8 @@ function QuestionControls({
   onUpdate,
 }: {
   question: HumanInputQuestion;
+  questionNumber: number | null;
+  labelledBy: string | undefined;
   draft: HumanInputAnswerDraft;
   fieldId: string;
   error: string | undefined;
@@ -479,6 +780,13 @@ function QuestionControls({
 }) {
   const errorId = `${fieldId}-error`;
   const helpId = `${fieldId}-help`;
+  const labelId = `${fieldId}-label`;
+  const promptId = `${fieldId}-prompt`;
+  const otherChoiceId = `${fieldId}-other-choice`;
+  const otherLabelId = `${fieldId}-other-label`;
+  const otherTextId = `${fieldId}-other-text`;
+  const visibleLabel = question.label ?? question.prompt;
+  const controlLabelId = showPromptChrome ? labelId : labelledBy;
   const hint =
     question.kind === "multi_select"
       ? messages.selectionHint(
@@ -488,22 +796,33 @@ function QuestionControls({
       : null;
   const describedBy =
     [
+      question.label && showPromptChrome ? promptId : null,
       question.helpText && showPromptChrome ? helpId : null,
       hint ? `${fieldId}-hint` : null,
       error ? errorId : null,
     ]
       .filter(Boolean)
       .join(" ") || undefined;
+  const selectOtherDraft = (current: HumanInputAnswerDraft): HumanInputAnswerDraft => ({
+    ...current,
+    otherSelected: true,
+    ...(question.kind === "single_select" ? { values: [] } : {}),
+  });
   return (
     <>
       {showPromptChrome ? (
         <>
           <div className="flex flex-wrap items-baseline gap-x-2">
             <label
+              id={labelId}
               htmlFor={question.kind === "text" ? fieldId : undefined}
               className="text-og-sm font-medium text-og-fg"
             >
-              {question.label ?? question.prompt}
+              {questionNumber === null ? null : (
+                <span className="mr-1.5 tabular-nums text-og-fg-muted">{questionNumber}.</span>
+              )}
+              {questionNumber === null ? null : " "}
+              {visibleLabel}
               {question.required && !allowSkip ? (
                 <span aria-hidden className="ml-1 text-og-status-failed">
                   *
@@ -515,7 +834,11 @@ function QuestionControls({
               ) : null}
             </label>
           </div>
-          {question.label ? <p className="text-og-sm text-og-fg-muted">{question.prompt}</p> : null}
+          {question.label ? (
+            <p id={promptId} className="text-og-sm text-og-fg-muted">
+              {question.prompt}
+            </p>
+          ) : null}
           {question.helpText ? (
             <p id={helpId} className="text-og-xs text-og-fg-subtle">
               {question.helpText}
@@ -556,6 +879,7 @@ function QuestionControls({
             }))
           }
           aria-invalid={Boolean(error)}
+          aria-labelledby={controlLabelId}
           aria-describedby={describedBy}
           autoFocus={autoFocus}
           rows={2}
@@ -564,6 +888,7 @@ function QuestionControls({
       ) : (
         <div
           role={question.kind === "single_select" ? "radiogroup" : "group"}
+          aria-labelledby={controlLabelId}
           aria-describedby={describedBy}
           className="flex flex-col gap-0.5"
         >
@@ -613,8 +938,8 @@ function QuestionControls({
               </label>
             );
           })}
-          {question.allowOther ? (
-            <label
+          {!question.skillReview ? (
+            <div
               className={cn(
                 "flex items-start gap-2.5 rounded-og-md px-2.5 py-2 transition-colors",
                 draft.otherSelected
@@ -623,8 +948,10 @@ function QuestionControls({
               )}
             >
               <input
+                id={otherChoiceId}
                 type={question.kind === "single_select" ? "radio" : "checkbox"}
                 name={question.kind === "single_select" ? fieldId : undefined}
+                aria-labelledby={otherLabelId}
                 checked={draft.otherSelected}
                 autoFocus={autoFocus && firstOption && question.options.length === 0}
                 onChange={(event) =>
@@ -639,22 +966,35 @@ function QuestionControls({
                 className="mt-2 accent-og-accent"
               />
               <span className="min-w-0 flex-1">
-                <span className="block text-og-sm font-medium">{messages.other}</span>
+                <label
+                  id={otherLabelId}
+                  htmlFor={otherChoiceId}
+                  className="block text-og-sm font-medium"
+                >
+                  {messages.other}
+                </label>
+                <label htmlFor={otherTextId} className="sr-only">
+                  {messages.other} answer for {visibleLabel}
+                </label>
                 <input
+                  id={otherTextId}
                   type="text"
                   value={draft.other}
-                  disabled={!draft.otherSelected || busy}
+                  disabled={busy}
                   placeholder="Type a value…"
-                  onChange={(event) =>
+                  onClick={() => onUpdate(selectOtherDraft)}
+                  onFocus={() => onUpdate(selectOtherDraft)}
+                  onChange={(event) => {
+                    const other = event.target.value;
                     onUpdate((current) => ({
-                      ...current,
-                      other: event.target.value,
-                    }))
-                  }
+                      ...selectOtherDraft(current),
+                      other,
+                    }));
+                  }}
                   className="mt-1.5 w-full rounded-og-sm border border-og-border bg-og-surface-1 px-2 py-1.5 text-og-sm text-og-fg outline-hidden focus:border-og-accent disabled:opacity-50"
                 />
               </span>
-            </label>
+            </div>
           ) : null}
         </div>
       )}
@@ -678,12 +1018,13 @@ export function answersFromDrafts(
   for (const question of questions) {
     const draft = drafts[question.id] ?? emptyDraft();
     const values = question.kind === "text" ? draft.values.filter(Boolean) : draft.values;
-    const other = draft.otherSelected ? draft.other.trim() : "";
-    const supplied = values.length + (other ? 1 : 0);
+    const other = draft.otherSelected ? draft.other : "";
+    const hasOther = Boolean(other.trim());
+    const supplied = values.length + (hasOther ? 1 : 0);
 
     // Other-selected-but-empty must win over generic "required" — otherwise the
     // user sees the wrong diagnosis next to a clearly selected control.
-    if (question.kind !== "text" && draft.otherSelected && !other) {
+    if (question.kind !== "text" && draft.otherSelected && !hasOther) {
       errors[question.id] = messages.otherRequired;
       continue;
     }
@@ -708,7 +1049,7 @@ export function answersFromDrafts(
       answers.push({
         questionId: question.id,
         values,
-        ...(other ? { other } : {}),
+        ...(hasOther ? { other } : {}),
       });
     }
   }