okstra 0.179.2 → 0.183.2

package/runtime/python/okstra_ctl/user_response.py

@@ -9,31 +9,57 @@ the ``## PLAN DECISION`` block used by the implementation wizard and the optiona
 from __future__ import annotations
 
 import argparse
+import base64
 import datetime as dt
+import hashlib
 import json
+import os
 import re
 import stat
 import sys
+import tempfile
+import uuid
+from collections.abc import Mapping
+from contextlib import contextmanager
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Optional
+from typing import Any, Iterator, Optional
 
 from okstra_ctl.report_views import (
     PLAN_DECISION_APPROVED,
+    RunMeta,
     normalize_direction_selection_identity,
     serialize_user_response, UserResponseEntry, UserPlanDecision,
-    UserReportAuthoring, infer_run_meta,
+    UserReportAuthoring, UserResponseAnalysisReview, UserDirectionSelection,
+    infer_run_meta,
     parse_expected_form_options,
+    resolve_recommended_option,
 )
 from okstra_ctl.report_view_artifacts import user_responses_dir_for_report
+from okstra_ctl.final_report_paths import (
+    final_report_data_path,
+    final_report_markdown_path,
+    is_report_record_path,
+)
+from okstra_ctl.json_boundary import (
+    JsonBoundaryError,
+    load_owned_object,
+    write_owned_object_atomic,
+)
+from okstra_ctl.final_report_schema import (
+    SchemaError,
+    load_schema_version,
+    validate as validate_report_schema,
+)
+from okstra_ctl.ids import slugify_task_segment
 from okstra_ctl.listing import list_runs, absolute_final_report_path
+from okstra_ctl.paths import resolve_under_root
+from okstra_ctl.run_context import dir_flock
 from okstra_ctl.clarification_items import (
+    ClarificationItem,
     read_clarification_rows,
-    scan_open_user_input,
-    section_1_present_but_unparsed,
     sidecar_answers,
     _section_1_slice,
-    _v2_report_data,
 )
 
 _PLAN_DECISION_HEADING_RE = re.compile(r"^## PLAN DECISION\s*$", re.MULTILINE)
@@ -42,6 +68,9 @@ _ANALYSIS_REVIEW_HEADING_RE = re.compile(r"^## ANALYSIS REVIEW\s*$", re.MULTILIN
 _DIRECTION_SELECTION_HEADING_RE = re.compile(
     r"^## DIRECTION SELECTION\s*$", re.MULTILINE
 )
+_REPORT_AUTHORING_HEADING_RE = re.compile(
+    r"^## REPORT AUTHORING\s*$", re.MULTILINE
+)
 _ANALYSIS_SIDECAR_HEADING_RE = re.compile(
     r"^## (?P<filename>user-response-[^\n]+\.md)\s*$", re.MULTILINE
 )
@@ -425,6 +454,25 @@ def parse_plan_decision(sidecar_text: str) -> Optional[PlanDecisionRecord]:
     )
 
 
+def parse_report_authoring(sidecar_text: str) -> UserReportAuthoring | None:
+    matches = list(_REPORT_AUTHORING_HEADING_RE.finditer(sidecar_text))
+    if not matches:
+        return None
+    if len(matches) != 1:
+        raise UserResponseError("REPORT AUTHORING requires exactly one block")
+    block = sidecar_text[matches[0].end():]
+    next_heading = _NEXT_RESPONSE_HEADING_RE.search(block)
+    if next_heading:
+        block = block[:next_heading.start()]
+    status = _field(block, "Status")
+    reason = _quoted_review_value(block, "Reason")
+    if status not in {"approved", "denied"} or not reason:
+        raise UserResponseError(
+            "REPORT AUTHORING requires approved/denied Status and Reason"
+        )
+    return UserReportAuthoring(status=status, reason=reason)
+
+
 _RESPONSE_HEADING_RE = re.compile(r"^## (?P<id>[A-Za-z][A-Za-z0-9]*-\d+)\s*$", re.MULTILINE)
 
 
@@ -531,6 +579,326 @@ def _seq_from_report(report: Path) -> str:
     return m.group(1) if m else ""
 
 
+@dataclass(frozen=True)
+class ResponseReportContext:
+    report_path: Path
+    markdown_path: Path
+    report_contract_version: str
+    task_key: str
+    task_type: str
+    seq: str
+    source_report: str
+    source_data: str
+    source_data_sha256: str
+    sidecar_path: Path
+    project_root: Path
+    task_root: Path
+    run_root: Path
+
+
+@dataclass(frozen=True)
+class ExistingSidecarState:
+    entries: tuple[UserResponseEntry, ...]
+    plan_decision: UserPlanDecision | None
+    analysis_review: UserResponseAnalysisReview | None
+    direction_selection: UserDirectionSelection | None
+    report_authoring: UserReportAuthoring | None
+    run_meta: RunMeta | None
+    created_at: str
+
+
+def _load_report_record(
+    report_path: Path, *, validate_schema: bool = False
+) -> dict[str, Any] | None:
+    data_path = final_report_data_path(report_path)
+    if not data_path.is_file():
+        if is_report_record_path(report_path):
+            raise UserResponseError(f"report record is missing: {data_path}")
+        return None
+    try:
+        record = load_owned_object(data_path, artifact="final report record")
+    except JsonBoundaryError as exc:
+        raise UserResponseError(str(exc)) from exc
+    version = record.get("schemaVersion")
+    if version not in {"2.0", "3.0"}:
+        raise UserResponseError(f"unsupported report contract: {version}")
+    if validate_schema:
+        try:
+            errors = validate_report_schema(record, load_schema_version(str(version)))
+        except SchemaError as exc:
+            raise UserResponseError(f"report schema could not be loaded: {exc}") from exc
+        if errors:
+            raise UserResponseError(f"report schema validation failed: {errors[0]}")
+    return record
+
+
+def _relative_from_runs(path: Path) -> str:
+    indices = [index for index, part in enumerate(path.parts) if part == "runs"]
+    return Path(*path.parts[indices[-1]:]).as_posix() if indices else path.name
+
+
+def _record_identity(record: Mapping[str, Any]) -> tuple[str, str]:
+    header = record.get("header")
+    if not isinstance(header, Mapping):
+        raise UserResponseError("report record header is missing")
+    task_key = header.get("taskKey")
+    task_type = header.get("taskType")
+    if not isinstance(task_key, str) or not task_key.strip():
+        raise UserResponseError("report record header.taskKey is missing")
+    if not isinstance(task_type, str) or not task_type.strip():
+        raise UserResponseError("report record header.taskType is missing")
+    return task_key.strip(), task_type.strip()
+
+
+def resolve_report_context(
+    report_path: Path, *, expected_task_key: str = ""
+) -> ResponseReportContext:
+    try:
+        resolved = report_path.resolve(strict=True)
+    except OSError as exc:
+        raise UserResponseError(f"report is unreadable: {report_path}") from exc
+    if resolved.parent.name != "reports":
+        raise UserResponseError("report must stay under an okstra reports directory")
+    record = _load_report_record(resolved)
+    markdown = final_report_markdown_path(resolved) if record else resolved
+    if record is None:
+        inferred = infer_run_meta(markdown, task_key=expected_task_key or None)
+        task_key, task_type = inferred.task_key, inferred.task_type
+        version = "1.0"
+    else:
+        task_key, task_type = _record_identity(record)
+        version = str(record["schemaVersion"])
+    if expected_task_key and task_key != expected_task_key:
+        raise UserResponseError(
+            f"task key does not match report: {expected_task_key} != {task_key}"
+        )
+    seq = _seq_from_report(resolved)
+    if not seq:
+        raise UserResponseError("report filename has no run sequence")
+    run_root = resolved.parent.parent
+    data_path = final_report_data_path(resolved) if record else None
+    source_data = _relative_from_runs(data_path) if data_path else ""
+    task_type_root = run_root.parent if run_root.name.startswith("stage-") else run_root
+    task_root = task_type_root.parent.parent
+    project_root = task_root.parents[3] if len(task_root.parents) >= 4 else task_root
+    return ResponseReportContext(
+        report_path=data_path or resolved,
+        markdown_path=markdown,
+        report_contract_version=version,
+        task_key=task_key,
+        task_type=task_type,
+        seq=seq,
+        source_report=_relative_from_runs(markdown),
+        source_data=source_data,
+        source_data_sha256=(
+            hashlib.sha256(data_path.read_bytes()).hexdigest() if data_path else ""
+        ),
+        sidecar_path=(
+            run_root
+            / "user-responses"
+            / f"user-response-{task_type}-{seq}.md"
+        ),
+        project_root=project_root,
+        task_root=task_root,
+        run_root=run_root,
+    )
+
+
+def _lexical_absolute(path: Path) -> Path:
+    return Path(os.path.abspath(os.fspath(path.expanduser())))
+
+
+def _reject_symlinks_below(root: Path, path: Path, label: str) -> None:
+    if root.is_symlink():
+        raise UserResponseError(f"{label} project root contains a symlink: {root}")
+    try:
+        relative = path.relative_to(root)
+    except ValueError as exc:
+        raise UserResponseError(f"{label} must stay under the project root") from exc
+    current = root
+    for part in relative.parts:
+        current = current / part
+        if not current.exists() and not current.is_symlink():
+            continue
+        try:
+            mode = current.lstat().st_mode
+        except OSError as exc:
+            raise UserResponseError(f"{label} path is unreadable: {current}") from exc
+        if stat.S_ISLNK(mode):
+            raise UserResponseError(f"{label} path contains a symlink: {current}")
+
+
+def _validate_owned_report_context(
+    report_path: Path,
+    *,
+    expected_task_key: str = "",
+    expected_project_root: Path | None = None,
+) -> ResponseReportContext:
+    lexical = _lexical_absolute(report_path)
+    data_path = _lexical_absolute(final_report_data_path(lexical))
+    if data_path.parent.name != "reports":
+        raise UserResponseError("report must stay under an okstra reports directory")
+    run_root = data_path.parent.parent
+    task_type_root = run_root.parent if run_root.name.startswith("stage-") else run_root
+    task_root = task_type_root.parent.parent
+    if (
+        task_type_root.parent.name != "runs"
+        or task_root.parent.parent.name != "tasks"
+        or task_root.parent.parent.parent.name != ".okstra"
+    ):
+        raise UserResponseError(
+            "report must stay under <PROJECT_ROOT>/.okstra/tasks/<group>/<task>/runs"
+        )
+    project_root = task_root.parent.parent.parent.parent
+    if expected_project_root is not None:
+        selected_root = _lexical_absolute(expected_project_root)
+        if selected_root.is_symlink() or not selected_root.is_dir():
+            raise UserResponseError(
+                f"selected project root must be a regular directory: {selected_root}"
+            )
+        if selected_root.resolve() != project_root.resolve():
+            raise UserResponseError("report does not belong to the selected project root")
+    relative = data_path.relative_to(project_root).as_posix()
+    if resolve_under_root(project_root, relative) is None:
+        raise UserResponseError("report resolves outside the selected project")
+    _reject_symlinks_below(project_root, data_path, "report")
+    markdown = _lexical_absolute(final_report_markdown_path(data_path))
+    _reject_symlinks_below(project_root, markdown, "report reading copy")
+    if not data_path.is_file() or not markdown.is_file():
+        raise UserResponseError("report record and reading copy must be regular files")
+    record = _load_report_record(data_path, validate_schema=True)
+    if record is None:
+        raise UserResponseError("typed transactions require a versioned report record")
+    context = resolve_report_context(data_path, expected_task_key=expected_task_key)
+    task_key_parts = context.task_key.split(":")
+    if len(task_key_parts) < 3:
+        raise UserResponseError("report task key must contain project, group, and task")
+    project_id = ":".join(task_key_parts[:-2])
+    project_config = project_root / ".okstra" / "project.json"
+    _reject_symlinks_below(project_root, project_config, "project config")
+    try:
+        config = load_owned_object(project_config, artifact="okstra project config")
+    except JsonBoundaryError as exc:
+        raise UserResponseError(str(exc)) from exc
+    frontmatter = record.get("frontmatter")
+    report_project_id = (
+        str(frontmatter.get("projectId") or "")
+        if isinstance(frontmatter, Mapping)
+        else ""
+    )
+    if config.get("projectId") != project_id or report_project_id != project_id:
+        raise UserResponseError("report project id does not match its project owner")
+    if (
+        slugify_task_segment(task_key_parts[-2]) != task_root.parent.name
+        or slugify_task_segment(task_key_parts[-1]) != task_root.name
+    ):
+        raise UserResponseError("report task key does not match its task directory")
+    if context.task_type != task_type_root.name:
+        raise UserResponseError("report task type does not match its run directory")
+    expected_name = f"final-report-{context.task_type}-{context.seq}.data.json"
+    if data_path.name != expected_name:
+        raise UserResponseError("report filename does not match its task type and run sequence")
+    if context.project_root != project_root.resolve():
+        raise UserResponseError("report project root does not match its canonical owner")
+    for owned_dir in (run_root / "state", run_root / "user-responses"):
+        _reject_symlinks_below(project_root, owned_dir, "user-response target")
+        if owned_dir.exists() and not owned_dir.is_dir():
+            raise UserResponseError(f"user-response target must be a directory: {owned_dir}")
+    _reject_symlinks_below(project_root, context.sidecar_path, "sidecar")
+    return context
+
+
+def _record_clarification_rows(record: Mapping[str, Any]) -> list[dict[str, Any]]:
+    entries = record.get("clarificationItems")
+    if not isinstance(entries, list):
+        raise UserResponseError("report clarificationItems must be an array")
+    rows: list[dict[str, Any]] = []
+    for entry in entries:
+        if not isinstance(entry, Mapping):
+            raise UserResponseError("report clarification item must be an object")
+        row_id, kind = entry.get("id"), entry.get("kind")
+        blocks, status = entry.get("blocks"), entry.get("status")
+        if not all(isinstance(value, str) and value for value in (row_id, blocks, status)):
+            raise UserResponseError("report clarification item identity is invalid")
+        item = ClarificationItem(
+            row_id=row_id,
+            kind=kind.lower() if isinstance(kind, str) else "",
+            blocks=blocks.lower(),
+            status=status.lower(),
+            raw_blocks=blocks,
+            raw_status=status,
+        )
+        options = entry.get("options")
+        rows.append({
+            "item": item,
+            "statement": str(entry.get("statement") or ""),
+            "expected_form": str(entry.get("expectedForm") or ""),
+            "options": (
+                [dict(option) for option in options if isinstance(option, Mapping)]
+                if isinstance(options, list)
+                else []
+            ),
+            "approval_context": (
+                dict(entry["approvalContext"])
+                if isinstance(entry.get("approvalContext"), Mapping)
+                else {}
+            ),
+        })
+    return rows
+
+
+def _all_report_rows(report_path: Path) -> tuple[list[dict[str, Any]], dict[str, Any] | None]:
+    record = _load_report_record(report_path)
+    return (
+        (_record_clarification_rows(record), record)
+        if record is not None
+        else (read_clarification_rows(report_path), None)
+    )
+
+
+def _implementation_option_projection(
+    context: ResponseReportContext,
+) -> tuple[list[str], str]:
+    record = _load_report_record(context.report_path) or {}
+    planning = record.get("implementationPlanning")
+    candidates = [
+        str(candidate.get("name"))
+        for candidate in (
+            planning.get("optionCandidates")
+            if isinstance(planning, Mapping)
+            else []
+        ) or []
+        if isinstance(candidate, Mapping) and candidate.get("name")
+    ]
+    recommended = planning.get("recommendedOption") if isinstance(planning, Mapping) else None
+    recommended_name = resolve_recommended_option(
+        str(recommended.get("name") or "") if isinstance(recommended, Mapping) else "",
+        tuple(candidates),
+    ) if candidates else ""
+    return candidates, recommended_name
+
+
+def _open_blocker_rows(report_path: Path) -> list[dict[str, Any]]:
+    rows, _ = _all_report_rows(report_path)
+    answered = sidecar_answers(report_path)
+    return [
+        row
+        for row in rows
+        if row["item"].blocks in {"approval", "next-phase"}
+        and row["item"].status in {"open", "answered"}
+        and row["item"].row_id not in answered
+    ]
+
+
+def _plan_decision_required(context: ResponseReportContext) -> bool:
+    if context.task_type != "implementation-planning":
+        return False
+    candidates, _ = _implementation_option_projection(context)
+    if not candidates:
+        return False
+    return _existing_sidecar_state(context.sidecar_path).plan_decision is None
+
+
 def list_awaiting_tasks(home: Path, project_id: str, limit: int) -> list[dict]:
     """사용자 답변을 기다리는 clarification 이 있는 태스크를 최신 report mtime 순으로.
 
@@ -550,22 +918,33 @@ def list_awaiting_tasks(home: Path, project_id: str, limit: int) -> list[dict]:
         report = absolute_final_report_path(row)
         if report is None or not report.is_file():
             continue
-        text = report.read_text(encoding="utf-8")
-        scan = scan_open_user_input(report)
-        base = {"taskKey": key, "taskType": row.get("taskType", ""),
-                "seq": _seq_from_report(report), "reportPath": str(report),
-                "reportMtime": report.stat().st_mtime}
-        if scan.unreadable_reason is not None:
-            # §1 heading exists but drifted → real warning; §1 simply absent → skip.
-            if section_1_present_but_unparsed(text):
-                out.append({**base, "openBlockerCount": 0, "openApprovalCount": 0,
-                            "unreadable": True})
+        try:
+            context = resolve_report_context(report)
+            blockers = _open_blocker_rows(context.report_path)
+            plan_required = _plan_decision_required(context)
+        except UserResponseError:
+            base = {"taskKey": key, "taskType": row.get("taskType", ""),
+                    "seq": _seq_from_report(report), "reportPath": str(report),
+                    "reportMtime": report.stat().st_mtime}
+            out.append({**base, "openBlockerCount": 0, "openApprovalCount": 0,
+                        "unreadable": True})
             continue
-        if not scan.blockers:
+        base = {
+            "taskKey": key,
+            "canonicalTaskKey": context.task_key,
+            "taskType": context.task_type,
+            "seq": context.seq,
+            "reportPath": str(report),
+            "normalizedReportPath": str(context.report_path),
+            "reportMtime": context.report_path.stat().st_mtime,
+        }
+        if not blockers and not plan_required:
             continue
-        approval_count = sum(1 for it in scan.blockers if it.blocks == "approval")
-        out.append({**base, "openBlockerCount": len(scan.blockers),
-                    "openApprovalCount": approval_count, "unreadable": False})
+        approval_count = sum(1 for row in blockers if row["item"].blocks == "approval")
+        out.append({**base, "openBlockerCount": len(blockers),
+                    "openApprovalCount": approval_count,
+                    "planDecisionRequired": plan_required,
+                    "unreadable": False})
     out.sort(key=lambda t: t["reportMtime"], reverse=True)
     return out[:limit] if limit > 0 else out
 
@@ -729,11 +1108,16 @@ def resolve_refs_from_record(data: dict, refs: list[str]) -> list[dict]:
 def show_open_rows(report_path: Path) -> dict:
     # 사이드카에 답이 있는 행은 사용자가 이미 답한 것이다. 리포트의 `Status` 는
     # 그 답을 반영하지 않으므로, 이걸 빼지 않으면 스킬이 같은 질문을 다시 묻는다.
-    answered = sidecar_answers(report_path)
-    record = _v2_report_data(report_path)
-    v1_text = None if record is not None else report_path.read_text(encoding="utf-8")
+    context = resolve_report_context(report_path)
+    answered = sidecar_answers(context.report_path)
+    report_rows, record = _all_report_rows(context.report_path)
+    v1_text = (
+        None
+        if record is not None
+        else context.markdown_path.read_text(encoding="utf-8")
+    )
     rows = []
-    for r in read_clarification_rows(report_path):
+    for r in report_rows:
         it = r["item"]
         if it.status not in ("open", "answered") or it.row_id in answered:
             continue
@@ -750,7 +1134,933 @@ def show_open_rows(report_path: Path) -> dict:
                      "options": r["options"] or _options_from_expected_form(expected),
                      "contextRefs": refs,
                      "resolvedRefs": resolved})
-    return {"reportPath": str(report_path), "rows": rows}
+    return {
+        "reportPath": str(report_path),
+        "normalizedReportPath": str(context.report_path),
+        "taskKey": context.task_key,
+        "taskType": context.task_type,
+        "reportContractVersion": context.report_contract_version,
+        "rows": rows,
+    }
+
+
+_TRANSACTION_PREFIX = "ur2."
+_TRANSACTION_ARTIFACT = "user-response transaction"
+_DIRECT_ANSWER_DISPOSITIONS = frozenset({"answer", "reframe"})
+_PLAN_DECISION_STATUSES = frozenset({
+    "approved",
+    "revision-requested",
+    "rejected",
+})
+_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+
+
+def _unexpected_keys(value: Mapping[str, Any], allowed: set[str], label: str) -> list[str]:
+    missing = sorted(allowed - set(value))
+    unexpected = sorted(set(value) - allowed)
+    errors = [f"{label} is missing fields: {', '.join(missing)}"] if missing else []
+    if unexpected:
+        errors.append(f"{label} has unexpected fields: {', '.join(unexpected)}")
+    return errors
+
+
+def _valid_sha256(value: object) -> bool:
+    return isinstance(value, str) and _SHA256_RE.fullmatch(value) is not None
+
+
+def _transaction_errors(payload: dict[str, Any]) -> list[str]:
+    errors = _unexpected_keys(
+        payload, {"schemaVersion", "transactionId", "anchor", "draft", "publication"},
+        "transaction",
+    )
+    if payload.get("schemaVersion") != "2.0":
+        errors.append("schemaVersion must be 2.0")
+    if not isinstance(payload.get("transactionId"), str) or not payload["transactionId"]:
+        errors.append("transactionId must be a non-empty string")
+    anchor = payload.get("anchor")
+    draft = payload.get("draft")
+    publication = payload.get("publication")
+    if not isinstance(anchor, Mapping):
+        errors.append("anchor must be an object")
+    else:
+        anchor_fields = {
+            "nonce", "transactionPath", "reportPath", "reportContractVersion",
+            "taskKey", "taskType", "runSeq", "sourceReport", "sourceData",
+            "sourceDataSha256", "sidecarPath", "baseSidecar", "createdAt",
+        }
+        errors.extend(_unexpected_keys(anchor, anchor_fields, "anchor"))
+        for field in anchor_fields - {"baseSidecar"}:
+            if not isinstance(anchor.get(field), str) or not anchor[field]:
+                errors.append(f"anchor.{field} must be a non-empty string")
+        if re.fullmatch(r"[0-9a-f]{32}", str(anchor.get("nonce") or "")) is None:
+            errors.append("anchor.nonce must be 32 lowercase hexadecimal characters")
+        if not _valid_sha256(anchor.get("sourceDataSha256")):
+            errors.append("anchor.sourceDataSha256 must be 64 lowercase hexadecimal characters")
+        base = anchor.get("baseSidecar")
+        if not isinstance(base, Mapping):
+            errors.append("anchor.baseSidecar must be an object")
+        else:
+            errors.extend(_unexpected_keys(base, {"exists", "sha256"}, "anchor.baseSidecar"))
+            exists = base.get("exists")
+            digest = base.get("sha256")
+            if not isinstance(exists, bool):
+                errors.append("anchor.baseSidecar.exists must be boolean")
+            if exists is True and not _valid_sha256(digest):
+                errors.append(
+                    "anchor.baseSidecar.sha256 must be 64 lowercase hexadecimal characters"
+                )
+            if exists is False and digest is not None:
+                errors.append("anchor.baseSidecar.sha256 must be null when the sidecar is absent")
+    if not isinstance(draft, Mapping):
+        errors.append("draft must be an object")
+    else:
+        errors.extend(_unexpected_keys(
+            draft, {"answers", "planDecision", "legacyReportAuthoring"}, "draft"
+        ))
+        answers = draft.get("answers")
+        if not isinstance(answers, list):
+            errors.append("draft.answers must be an array")
+        else:
+            for index, answer in enumerate(answers):
+                label = f"draft.answers[{index}]"
+                if not isinstance(answer, Mapping):
+                    errors.append(f"{label} must be an object")
+                    continue
+                mode = answer.get("mode")
+                allowed = (
+                    {"mode", "id", "kind", "optionNumber"}
+                    if mode == "option"
+                    else {"mode", "id", "kind", "value", "rationale", "disposition"}
+                )
+                errors.extend(_unexpected_keys(answer, allowed, label))
+                if mode not in {"direct", "option"}:
+                    errors.append(f"{label}.mode must be direct or option")
+                for field in ("id", "kind"):
+                    if not isinstance(answer.get(field), str) or not answer[field]:
+                        errors.append(f"{label}.{field} must be a non-empty string")
+                if mode == "option":
+                    number = answer.get("optionNumber")
+                    if not isinstance(number, int) or isinstance(number, bool) or number < 1:
+                        errors.append(f"{label}.optionNumber must be a positive integer")
+                elif mode == "direct":
+                    if not isinstance(answer.get("value"), str) or not answer["value"]:
+                        errors.append(f"{label}.value must be a non-empty string")
+                    if not isinstance(answer.get("rationale"), str):
+                        errors.append(f"{label}.rationale must be a string")
+                    if answer.get("disposition") not in _DIRECT_ANSWER_DISPOSITIONS:
+                        errors.append(f"{label}.disposition is invalid for a direct answer")
+        for field in ("planDecision", "legacyReportAuthoring"):
+            value = draft.get(field)
+            if value is not None and not isinstance(value, Mapping):
+                errors.append(f"draft.{field} must be an object or null")
+        decision = draft.get("planDecision")
+        if isinstance(decision, Mapping):
+            errors.extend(_unexpected_keys(
+                decision, {"status", "implementationOption", "reason"},
+                "draft.planDecision",
+            ))
+            if decision.get("status") not in _PLAN_DECISION_STATUSES:
+                errors.append("draft.planDecision.status is invalid")
+            for field in ("implementationOption", "reason"):
+                if not isinstance(decision.get(field), str):
+                    errors.append(f"draft.planDecision.{field} must be a string")
+            if decision.get("status") != "approved" and not decision.get("reason"):
+                errors.append("draft.planDecision.reason is required")
+        authoring = draft.get("legacyReportAuthoring")
+        if isinstance(authoring, Mapping):
+            errors.extend(_unexpected_keys(
+                authoring, {"status", "reason"}, "draft.legacyReportAuthoring"
+            ))
+            if authoring.get("status") not in {"approved", "denied"}:
+                errors.append("draft.legacyReportAuthoring.status is invalid")
+            if not isinstance(authoring.get("reason"), str) or not authoring["reason"]:
+                errors.append("draft.legacyReportAuthoring.reason must be a non-empty string")
+    if not isinstance(publication, Mapping):
+        errors.append("publication must be an object")
+    else:
+        errors.extend(_unexpected_keys(
+            publication, {"status", "intentSha256", "finalizedSha256"}, "publication"
+        ))
+        status_value = publication.get("status")
+        intent = publication.get("intentSha256")
+        finalized = publication.get("finalizedSha256")
+        if status_value not in {"draft", "intent-recorded", "finalized"}:
+            errors.append("publication.status is invalid")
+        if status_value == "draft" and (intent is not None or finalized is not None):
+            errors.append("publication draft digests must be null")
+        if status_value == "intent-recorded" and (
+            not _valid_sha256(intent) or finalized is not None
+        ):
+            errors.append("publication intent digest must be valid and finalized digest null")
+        if status_value == "finalized" and (
+            not _valid_sha256(intent) or not _valid_sha256(finalized) or intent != finalized
+        ):
+            errors.append("publication finalized digests must be matching sha256 values")
+    return errors
+
+
+def _canonical_anchor_digest(anchor: Mapping[str, Any]) -> str:
+    encoded = json.dumps(
+        anchor, ensure_ascii=False, sort_keys=True, separators=(",", ":")
+    ).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def _encode_transaction_path(path: Path, anchor: Mapping[str, Any]) -> str:
+    encoded = base64.urlsafe_b64encode(str(path).encode()).decode().rstrip("=")
+    return f"{_TRANSACTION_PREFIX}{encoded}.{_canonical_anchor_digest(anchor)}"
+
+
+def _decode_transaction_token(transaction_id: str) -> tuple[Path, str]:
+    if not transaction_id.startswith(_TRANSACTION_PREFIX):
+        raise UserResponseError("invalid user-response transaction id")
+    encoded_and_digest = transaction_id[len(_TRANSACTION_PREFIX):]
+    try:
+        encoded, anchor_digest = encoded_and_digest.rsplit(".", 1)
+        decoded = base64.urlsafe_b64decode(encoded + "=" * (-len(encoded) % 4))
+        path = Path(decoded.decode())
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise UserResponseError("invalid user-response transaction id") from exc
+    if not _valid_sha256(anchor_digest):
+        raise UserResponseError("invalid user-response transaction anchor digest")
+    if (
+        not path.is_absolute()
+        or path.name != "draft.json"
+        or path.parent.parent.name != "user-response-transactions"
+        or path.parent.parent.parent.name != "state"
+        or re.fullmatch(r"[0-9a-f]{32}", path.parent.name) is None
+    ):
+        raise UserResponseError("invalid user-response transaction path")
+    return path, anchor_digest
+
+
+def _transaction_path(transaction_id: str) -> Path:
+    path, _ = _decode_transaction_token(transaction_id)
+    return path
+
+
+def _load_transaction(transaction_id: str) -> tuple[Path, dict[str, Any]]:
+    path, expected_anchor_digest = _decode_transaction_token(transaction_id)
+    try:
+        payload = load_owned_object(
+            path,
+            artifact=_TRANSACTION_ARTIFACT,
+            validate_cross_fields=_transaction_errors,
+        )
+    except JsonBoundaryError as exc:
+        raise UserResponseError(str(exc)) from exc
+    anchor = payload["anchor"]
+    if _canonical_anchor_digest(anchor) != expected_anchor_digest:
+        raise UserResponseError("transaction anchor digest does not match its token")
+    if payload["transactionId"] != transaction_id:
+        raise UserResponseError("transaction id does not match its state")
+    return path, payload
+
+
+def _write_transaction(path: Path, payload: Mapping[str, Any]) -> None:
+    try:
+        write_owned_object_atomic(
+            path,
+            payload,
+            artifact=_TRANSACTION_ARTIFACT,
+            validate_cross_fields=_transaction_errors,
+        )
+    except JsonBoundaryError as exc:
+        raise UserResponseError(str(exc)) from exc
+
+
+def _context_from_transaction(
+    path: Path, payload: Mapping[str, Any]
+) -> ResponseReportContext:
+    anchor = payload["anchor"]
+    context = _validate_owned_report_context(
+        Path(str(anchor["reportPath"])),
+        expected_task_key=str(anchor["taskKey"]),
+    )
+    expected_path = (
+        context.run_root
+        / "state"
+        / "user-response-transactions"
+        / path.parent.name
+        / "draft.json"
+    )
+    comparisons = {
+        "nonce": path.parent.name,
+        "reportContractVersion": context.report_contract_version,
+        "taskType": context.task_type,
+        "taskKey": context.task_key,
+        "runSeq": context.seq,
+        "sourceReport": context.source_report,
+        "sourceData": context.source_data,
+        "sourceDataSha256": context.source_data_sha256,
+        "reportPath": str(context.report_path),
+        "sidecarPath": str(context.sidecar_path),
+        "transactionPath": str(expected_path),
+    }
+    for field, expected in comparisons.items():
+        if str(anchor.get(field) or "") != expected:
+            raise UserResponseError(f"transaction {field} no longer matches report context")
+    if path != expected_path:
+        raise UserResponseError("transaction canonical path no longer matches report context")
+    return context
+
+
+def _sidecar_snapshot(path: Path) -> dict[str, Any]:
+    if not path.exists() and not path.is_symlink():
+        return {"exists": False, "sha256": None}
+    if not path.is_file() or path.is_symlink():
+        raise UserResponseError(f"sidecar must be a regular file: {path}")
+    return {"exists": True, "sha256": hashlib.sha256(path.read_bytes()).hexdigest()}
+
+
+def _validate_draft_against_context(
+    draft: Mapping[str, Any], context: ResponseReportContext
+) -> None:
+    rows, _ = _all_report_rows(context.report_path)
+    rows_by_id = {row["item"].row_id: row for row in rows}
+    seen: set[str] = set()
+    for answer in draft["answers"]:
+        clarification_id = str(answer["id"])
+        if clarification_id in seen:
+            raise UserResponseError(
+                f"duplicate clarification id in transaction draft: {clarification_id}"
+            )
+        seen.add(clarification_id)
+        row = rows_by_id.get(clarification_id)
+        if row is None:
+            raise UserResponseError(
+                f"clarification id does not exist in report: {clarification_id}"
+            )
+        if row["item"].status not in {"open", "answered"}:
+            raise UserResponseError(
+                f"clarification is resolved or closed: {clarification_id}"
+            )
+        if answer["kind"] != row["item"].kind:
+            raise UserResponseError(
+                f"clarification kind does not match {clarification_id}"
+            )
+        if answer["mode"] == "option":
+            number = int(answer["optionNumber"])
+            if number > len(row["options"]):
+                raise UserResponseError(
+                    f"option number does not exist for {clarification_id}: {number}"
+                )
+    decision = draft.get("planDecision")
+    if isinstance(decision, Mapping):
+        candidates, _ = _implementation_option_projection(context)
+        selected = str(decision.get("implementationOption") or "")
+        if selected and selected not in candidates:
+            raise UserResponseError(
+                f"implementation option is not a report candidate: {selected}"
+            )
+    authoring = draft.get("legacyReportAuthoring")
+    if context.report_contract_version != "2.0" and authoring is not None:
+        raise UserResponseError(
+            "legacy report authoring is allowed only for report contract 2.0"
+        )
+
+
+@contextmanager
+def _locked_transaction(
+    transaction_id: str, *, mutable: bool = False
+) -> Iterator[tuple[Path, dict[str, Any], ResponseReportContext]]:
+    decoded = _transaction_path(transaction_id)
+    preflight_path, preflight_payload = _load_transaction(transaction_id)
+    preflight_context = _context_from_transaction(preflight_path, preflight_payload)
+    state_dir = preflight_context.run_root / "state"
+    for candidate in (
+        state_dir,
+        decoded.parent.parent,
+        decoded.parent,
+        decoded,
+    ):
+        if candidate.is_symlink():
+            raise UserResponseError(
+                f"transaction state path contains a symlink: {candidate}"
+            )
+    with dir_flock(state_dir, ".user-response-transactions.lock"):
+        path, payload = _load_transaction(transaction_id)
+        context = _context_from_transaction(path, payload)
+        _validate_draft_against_context(payload["draft"], context)
+        if mutable and payload["publication"]["status"] != "draft":
+            raise UserResponseError("user-response transaction publication has already begun")
+        yield path, payload, context
+
+
+def begin_response(report_path: Path, task_key: str) -> str:
+    context = _validate_owned_report_context(report_path, expected_task_key=task_key)
+    transaction_dir = (
+        context.report_path.parent.parent
+        / "state"
+        / "user-response-transactions"
+        / uuid.uuid4().hex
+    )
+    path = transaction_dir / "draft.json"
+    created_at = dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    state_dir = context.run_root / "state"
+    if state_dir.is_symlink():
+        raise UserResponseError(f"transaction state path contains a symlink: {state_dir}")
+    with dir_flock(state_dir, ".user-response-transactions.lock"):
+        anchor = {
+            "nonce": path.parent.name,
+            "transactionPath": str(path),
+            "reportPath": str(context.report_path),
+            "reportContractVersion": context.report_contract_version,
+            "taskKey": context.task_key,
+            "taskType": context.task_type,
+            "runSeq": context.seq,
+            "sourceReport": context.source_report,
+            "sourceData": context.source_data,
+            "sourceDataSha256": context.source_data_sha256,
+            "sidecarPath": str(context.sidecar_path),
+            "baseSidecar": _sidecar_snapshot(context.sidecar_path),
+            "createdAt": created_at,
+        }
+        transaction_id = _encode_transaction_path(path, anchor)
+        payload = {
+            "schemaVersion": "2.0",
+            "transactionId": transaction_id,
+            "anchor": anchor,
+            "draft": {
+                "answers": [],
+                "planDecision": None,
+                "legacyReportAuthoring": None,
+            },
+            "publication": {
+                "status": "draft",
+                "intentSha256": None,
+                "finalizedSha256": None,
+            },
+        }
+        _write_transaction(path, payload)
+    return transaction_id
+
+
+def _read_body_file(
+    path: Path,
+    field: str,
+    context: ResponseReportContext,
+    *,
+    required: bool = True,
+) -> str:
+    lexical = _lexical_absolute(path)
+    temp_root = context.project_root / ".okstra/tmp/user-response"
+    try:
+        relative = lexical.relative_to(temp_root)
+    except ValueError as exc:
+        raise UserResponseError(f"{field} file must stay under {temp_root}") from exc
+    if resolve_under_root(temp_root, relative.as_posix()) is None:
+        raise UserResponseError(f"{field} file must stay under {temp_root}")
+    _reject_symlinks_below(context.project_root, lexical, f"{field} file")
+    if not lexical.is_file() or lexical.is_symlink():
+        raise UserResponseError(f"{field} file must be a regular file: {lexical}")
+    try:
+        value = lexical.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeError, ValueError) as exc:
+        raise UserResponseError(f"{field} file is unreadable: {lexical}") from exc
+    if required and not value:
+        raise UserResponseError(f"{field} file must not be empty")
+    return value
+
+
+def answer_response(
+    transaction_id: str,
+    clarification_id: str,
+    kind: str,
+    disposition: str | None,
+    value_file: Path | None,
+    rationale_file: Path | None,
+    option_number: int | None = None,
+) -> None:
+    option_mode = option_number is not None
+    if option_mode and any((disposition, value_file, rationale_file)):
+        raise UserResponseError(
+            "--option-number cannot be combined with direct answer fields"
+        )
+    if not option_mode and (not disposition or value_file is None):
+        raise UserResponseError(
+            "direct answers require --disposition and --value-file"
+        )
+    with _locked_transaction(transaction_id, mutable=True) as (path, payload, context):
+        rows, _ = _all_report_rows(context.report_path)
+        matching = [row for row in rows if row["item"].row_id == clarification_id]
+        if len(matching) != 1:
+            raise UserResponseError(
+                f"clarification id does not exist in report: {clarification_id}"
+            )
+        row = matching[0]
+        if row["item"].status not in {"open", "answered"}:
+            raise UserResponseError(
+                f"clarification is resolved or closed: {clarification_id}"
+            )
+        if row["item"].kind != kind:
+            raise UserResponseError(f"clarification kind does not match {clarification_id}")
+        if option_mode:
+            options = row["options"]
+            if option_number is None or option_number < 1 or option_number > len(options):
+                raise UserResponseError(
+                    f"option number does not exist for {clarification_id}: {option_number}"
+                )
+            answer = {
+                "mode": "option",
+                "id": clarification_id,
+                "kind": kind,
+                "optionNumber": option_number,
+            }
+        else:
+            if disposition not in _DIRECT_ANSWER_DISPOSITIONS:
+                raise UserResponseError(f"invalid answer disposition: {disposition}")
+            answer = {
+                "mode": "direct",
+                "id": clarification_id,
+                "kind": kind,
+                "value": _read_body_file(value_file, "answer", context),
+                "rationale": (
+                    " ".join(
+                        _read_body_file(rationale_file, "rationale", context).splitlines()
+                    )
+                    if rationale_file
+                    else ""
+                ),
+                "disposition": disposition,
+            }
+        answers = [
+            existing for existing in payload["draft"]["answers"]
+            if existing.get("id") != clarification_id
+        ]
+        payload["draft"]["answers"] = [*answers, answer]
+        _write_transaction(path, payload)
+
+
+def set_plan_decision(
+    transaction_id: str,
+    status: str,
+    implementation_option: str,
+    reason_file: Path | None,
+) -> None:
+    with _locked_transaction(transaction_id, mutable=True) as (path, payload, context):
+        if status not in _PLAN_DECISION_STATUSES:
+            raise UserResponseError(f"invalid plan decision status: {status}")
+        reason = (
+            _read_body_file(reason_file, "plan decision reason", context)
+            if reason_file else ""
+        )
+        if status != "approved" and not reason:
+            raise UserResponseError(f"plan decision {status} requires --reason-file")
+        selected = implementation_option.strip()
+        candidates, _ = _implementation_option_projection(context)
+        if selected and selected not in candidates:
+            raise UserResponseError(
+                f"implementation option is not a report candidate: {selected}"
+            )
+        payload["draft"]["planDecision"] = {
+            "status": status,
+            "implementationOption": selected,
+            "reason": reason,
+        }
+        _write_transaction(path, payload)
+
+
+def set_legacy_report_authoring(
+    transaction_id: str, status: str, reason_file: Path
+) -> None:
+    with _locked_transaction(transaction_id, mutable=True) as (path, payload, context):
+        if context.report_contract_version != "2.0":
+            raise UserResponseError(
+                "legacy report authoring is allowed only for report contract 2.0"
+            )
+        if status not in {"approved", "denied"}:
+            raise UserResponseError(f"invalid legacy report authoring status: {status}")
+        payload["draft"]["legacyReportAuthoring"] = {
+            "status": status,
+            "reason": _read_body_file(
+                reason_file, "legacy report authoring reason", context
+            ),
+        }
+        _write_transaction(path, payload)
+
+
+def _existing_sidecar_state(sidecar: Path) -> ExistingSidecarState:
+    if not sidecar.exists():
+        return ExistingSidecarState(
+            entries=(),
+            plan_decision=None,
+            analysis_review=None,
+            direction_selection=None,
+            report_authoring=None,
+            run_meta=None,
+            created_at="",
+        )
+    if not sidecar.is_file() or sidecar.is_symlink():
+        raise UserResponseError(f"sidecar must be a regular file: {sidecar}")
+    text = sidecar.read_text(encoding="utf-8")
+    plan_record = parse_plan_decision(text)
+    review_record = parse_analysis_review(text)
+    direction_record = parse_direction_selection(text)
+    return ExistingSidecarState(
+        entries=tuple(parse_user_response_entries(text)),
+        plan_decision=(
+            UserPlanDecision(
+                plan_record.status,
+                plan_record.implementation_option,
+                plan_record.reason,
+            )
+            if plan_record
+            else None
+        ),
+        analysis_review=(
+            UserResponseAnalysisReview(
+                review_record.status,
+                review_record.affected_ids,
+                review_record.reason,
+                review_record.additional_evidence,
+                review_record.requested_scope_change,
+            )
+            if review_record
+            else None
+        ),
+        direction_selection=(
+            UserDirectionSelection(
+                direction_record.option_id,
+                direction_record.option_name,
+                direction_record.confirmed,
+                direction_record.selection_note,
+                direction_record.constraints,
+            )
+            if direction_record
+            else None
+        ),
+        report_authoring=parse_report_authoring(text),
+        run_meta=RunMeta(
+            task_key=_sidecar_metadata_value(text, "task-key"),
+            task_type=_sidecar_metadata_value(text, "task-type"),
+            seq=_sidecar_metadata_value(text, "seq"),
+            source_report=_sidecar_metadata_value(text, "source-report"),
+            source_data=_sidecar_metadata_value(text, "source-data"),
+            source_data_sha256=_sidecar_metadata_value(
+                text, "source-data-sha256"
+            ),
+        ),
+        created_at=_sidecar_metadata_value(text, "created-at"),
+    )
+
+
+def _lossless_existing_sidecar_state(sidecar: Path) -> tuple[
+    str,
+    ExistingSidecarState,
+]:
+    text = sidecar.read_text(encoding="utf-8")
+    known_blocks = {
+        "PLAN DECISION",
+        "ANALYSIS REVIEW",
+        "DIRECTION SELECTION",
+        "REPORT AUTHORING",
+    }
+    seen: set[str] = set()
+    for match in re.finditer(r"^## (?P<title>[^\r\n]+)\s*$", text, re.MULTILINE):
+        title = match.group("title").strip()
+        if title not in known_blocks and re.fullmatch(
+            r"[A-Za-z][A-Za-z0-9]*-\d+", title
+        ) is None:
+            raise UserResponseError(
+                "existing sidecar cannot be losslessly updated; bytes preserved "
+                f"(unknown block: {title})"
+            )
+        if title in seen:
+            raise UserResponseError(
+                "existing sidecar cannot be losslessly updated; bytes preserved "
+                f"(duplicate block: {title})"
+            )
+        seen.add(title)
+    try:
+        state = _existing_sidecar_state(sidecar)
+        if state.run_meta is None:
+            raise UserResponseError("existing sidecar provenance is missing")
+        canonical = serialize_user_response(
+            run_meta=state.run_meta,
+            entries=list(state.entries),
+            created_at=state.created_at,
+            plan_decision=state.plan_decision,
+            analysis_review=state.analysis_review,
+            direction_selection=state.direction_selection,
+            report_authoring=state.report_authoring,
+        )
+    except (UserResponseError, ValueError) as exc:
+        raise UserResponseError(
+            "existing sidecar cannot be losslessly updated; bytes preserved "
+            f"({exc})"
+        ) from exc
+    if canonical != text:
+        raise UserResponseError(
+            "existing sidecar cannot be losslessly updated; bytes preserved"
+        )
+    return text, state
+
+
+def _atomic_write_sidecar(path: Path, body: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.parent.is_symlink():
+        raise UserResponseError(f"sidecar directory must not be a symlink: {path.parent}")
+    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    temporary = Path(temporary_name)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(body)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    except OSError as exc:
+        raise UserResponseError(f"could not publish sidecar: {path}") from exc
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def _transaction_decision(payload: Mapping[str, Any]) -> UserPlanDecision | None:
+    decision = payload.get("planDecision")
+    if not isinstance(decision, Mapping):
+        return None
+    return UserPlanDecision(
+        status=str(decision.get("status") or ""),
+        implementation_option=str(decision.get("implementationOption") or ""),
+        reason=str(decision.get("reason") or ""),
+    )
+
+
+def _transaction_authoring(payload: Mapping[str, Any]) -> UserReportAuthoring | None:
+    authoring = payload.get("legacyReportAuthoring")
+    if not isinstance(authoring, Mapping):
+        return None
+    return UserReportAuthoring(
+        status=str(authoring.get("status") or ""),
+        reason=str(authoring.get("reason") or ""),
+    )
+
+
+def _render_transaction_sidecar(
+    payload: Mapping[str, Any], context: ResponseReportContext
+) -> str:
+    anchor = payload["anchor"]
+    draft = payload["draft"]
+    sidecar = context.sidecar_path
+    existing_text = ""
+    if sidecar.exists():
+        existing_text, existing_state = _lossless_existing_sidecar_state(sidecar)
+    else:
+        existing_state = _existing_sidecar_state(sidecar)
+    if (
+        existing_text
+        and not draft["answers"]
+        and draft["planDecision"] is None
+        and draft["legacyReportAuthoring"] is None
+    ):
+        return existing_text
+    merged = {entry.response_id: entry for entry in existing_state.entries}
+    report_rows, _ = _all_report_rows(context.report_path)
+    rows_by_id = {row["item"].row_id: row for row in report_rows}
+    for answer in draft["answers"]:
+        if answer["mode"] == "option":
+            option = rows_by_id[str(answer["id"])]["options"][answer["optionNumber"] - 1]
+            value = str(option.get("answer") or "")
+            rationale = str(option.get("rationale") or "")
+            disposition = str(option.get("disposition") or "answer")
+        else:
+            value = str(answer["value"])
+            rationale = str(answer.get("rationale") or "")
+            disposition = str(answer["disposition"])
+        merged[str(answer["id"])] = UserResponseEntry(
+            response_id=str(answer["id"]),
+            kind=str(answer["kind"]),
+            value=value,
+            rationale=rationale or None,
+            disposition=disposition,
+        )
+    if existing_state.run_meta is not None:
+        run_meta = existing_state.run_meta
+        created_at = existing_state.created_at
+    else:
+        run_meta = RunMeta(
+            task_key=context.task_key,
+            task_type=context.task_type,
+            seq=context.seq,
+            source_report=context.source_report,
+            source_data=context.source_data,
+            source_data_sha256=context.source_data_sha256,
+        )
+        created_at = str(anchor["createdAt"])
+    return serialize_user_response(
+        run_meta=run_meta,
+        entries=list(merged.values()),
+        created_at=created_at,
+        plan_decision=(
+            _transaction_decision(draft) or existing_state.plan_decision
+        ),
+        analysis_review=existing_state.analysis_review,
+        direction_selection=existing_state.direction_selection,
+        report_authoring=(
+            _transaction_authoring(draft) or existing_state.report_authoring
+        ),
+    )
+
+
+def finalize_response(transaction_id: str) -> Path:
+    with _locked_transaction(transaction_id) as (path, payload, context):
+        sidecar = context.sidecar_path
+        actual = _sidecar_snapshot(sidecar)
+        publication = payload["publication"]
+        status_value = publication["status"]
+        finalized_digest = publication["finalizedSha256"]
+        if status_value == "finalized":
+            if (
+                actual["exists"] is not True
+                or not _valid_sha256(finalized_digest)
+                or actual["sha256"] != finalized_digest
+            ):
+                raise UserResponseError(
+                    "finalized transaction sidecar digest no longer matches"
+                )
+            return sidecar
+        base = payload["anchor"]["baseSidecar"]
+        intent_digest = publication["intentSha256"]
+        if (
+            status_value == "intent-recorded"
+            and _valid_sha256(intent_digest)
+            and actual["exists"] is True
+            and actual["sha256"] == intent_digest
+        ):
+            publication["status"] = "finalized"
+            publication["finalizedSha256"] = intent_digest
+            _write_transaction(path, payload)
+            return sidecar
+        if actual != base:
+            raise UserResponseError(
+                "stale user-response transaction: sidecar changed after begin"
+            )
+        body = _render_transaction_sidecar(payload, context)
+        rendered_digest = hashlib.sha256(body.encode("utf-8")).hexdigest()
+        if status_value == "intent-recorded" and intent_digest != rendered_digest:
+            raise UserResponseError("transaction publish intent no longer matches draft")
+        if status_value == "draft":
+            publication["status"] = "intent-recorded"
+            publication["intentSha256"] = rendered_digest
+            _write_transaction(path, payload)
+        if not (
+            actual["exists"] is True
+            and actual["sha256"] == rendered_digest
+        ):
+            _atomic_write_sidecar(sidecar, body)
+        publication["status"] = "finalized"
+        publication["finalizedSha256"] = rendered_digest
+        _write_transaction(path, payload)
+        return sidecar
+
+
+def format_list_view(rows: list[dict[str, Any]]) -> str:
+    lines = ["USER RESPONSE TASKS", f"Count: {len(rows)}"]
+    for index, row in enumerate(rows, start=1):
+        status = "unreadable" if row.get("unreadable") else "ready"
+        lines.extend([
+            "",
+            f"[{index}]",
+            f"Task key: {row.get('canonicalTaskKey', row.get('taskKey', ''))}",
+            f"Task type: {row.get('taskType', '')}",
+            f"Run sequence: {row.get('seq', '')}",
+            f"Report: {row.get('normalizedReportPath', row.get('reportPath', ''))}",
+            f"Open items: {row.get('openBlockerCount', 0)}",
+            f"Open approval items: {row.get('openApprovalCount', 0)}",
+            f"Plan decision required: {'yes' if row.get('planDecisionRequired') else 'no'}",
+            f"Status: {status}",
+        ])
+    return "\n".join(lines) + "\n"
+
+
+def _option_view(option: Mapping[str, Any], index: int) -> list[str]:
+    scope = option.get("scopeImpact")
+    scope_text = ", ".join(str(item) for item in scope) if isinstance(scope, list) else ""
+    effects = option.get("scopeEffects")
+    effects_text = ", ".join(str(item) for item in effects) if isinstance(effects, list) else ""
+    return [
+        f"Option {index}:",
+        f"  Role: {option.get('role', '')}",
+        f"  Answer: {option.get('answer', '')}",
+        f"  Rationale: {option.get('rationale', '')}",
+        f"  Scope impact: {scope_text or 'not stated in the report'}",
+        f"  Added work: {option.get('addedWork') or 'not stated in the report'}",
+        f"  Direction change: {option.get('directionChange') or 'not stated in the report'}",
+        f"  Disposition: {option.get('disposition') or 'answer'}",
+        f"  Reach: {option.get('reach') or 'not stated in the report'}",
+        f"  Scope effects: {effects_text or 'not stated in the report'}",
+    ]
+
+
+def format_show_view(report_path: Path, project_root: Path) -> str:
+    context = _validate_owned_report_context(
+        report_path, expected_project_root=project_root
+    )
+    rows, record = _all_report_rows(context.report_path)
+    state = _existing_sidecar_state(context.sidecar_path)
+    current = {entry.response_id: entry for entry in state.entries}
+    lines = [
+        "USER RESPONSE REPORT",
+        f"Report: {context.report_path}",
+        f"Task key: {context.task_key}",
+        f"Task type: {context.task_type}",
+        f"Report contract: {context.report_contract_version}",
+        f"Clarification items: {len(rows)}",
+        "Current plan decision: "
+        f"{state.plan_decision.status if state.plan_decision else 'none'}",
+        "Current legacy report authoring: "
+        f"{state.report_authoring.status if state.report_authoring else 'none'}",
+    ]
+    candidates, recommended_name = _implementation_option_projection(context)
+    if candidates:
+        lines.append("Plan option candidates:")
+        for index, candidate in enumerate(candidates, start=1):
+            lines.extend([
+                f"Plan option {index}: {candidate}",
+                f"  Recommended: {'yes' if candidate == recommended_name else 'no'}",
+                "  Current decision: "
+                f"{'yes' if state.plan_decision and state.plan_decision.implementation_option == candidate else 'no'}",
+            ])
+    for row in rows:
+        item = row["item"]
+        if item.status not in {"open", "answered"} or item.row_id in current:
+            continue
+        refs = sorted(set(_SECTION_REF_RE.findall(
+            row["statement"] + " " + row["expected_form"]
+        )))
+        resolved = (
+            resolve_refs_from_record(record, refs)
+            if record is not None
+            else resolve_refs(context.markdown_path.read_text(encoding="utf-8"), refs)
+        )
+        response = current.get(item.row_id)
+        lines.extend([
+            "",
+            f"[{item.row_id}]",
+            f"Kind: {item.kind}",
+            f"Blocks: {item.blocks}",
+            f"Report status: {item.status}",
+            f"Question: {row['statement']}",
+            f"Expected form: {row['expected_form']}",
+            f"Current response: {response.value if response else 'none'}",
+            f"Current disposition: {response.disposition if response else 'none'}",
+            "Options:",
+        ])
+        approval = row.get("approval_context") or {}
+        if approval:
+            lines.extend([
+                f"Approval classification: {approval.get('classification', '')}",
+                f"Approval unblock condition: {approval.get('unblockCondition', '')}",
+                f"Approval recommended disposition: {approval.get('recommendedDisposition', '')}",
+            ])
+        for index, option in enumerate(row["options"], start=1):
+            lines.extend(_option_view(option, index))
+        lines.append("Context:")
+        lines.extend(
+            f"- {ref['ref']}: {ref['definition'] or 'not stated in the report'}"
+            for ref in resolved
+        )
+    return "\n".join(lines) + "\n"
 
 
 def write_sidecar(report_path: Path, answers: list[dict],
@@ -790,51 +2100,106 @@ def write_sidecar(report_path: Path, answers: list[dict],
     return sidecar
 
 
-def main(argv: Optional[list[str]] = None) -> int:
+def _add_list_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--home", required=True)
+    parser.add_argument("--project", required=True)
+    parser.add_argument("--limit", type=int, default=3)
+
+
+def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="okstra user-response")
     sub = parser.add_subparsers(dest="cmd", required=True)
+    _add_list_arguments(sub.add_parser("list"))
+    _add_list_arguments(sub.add_parser("list-view"))
+    sub.add_parser("show").add_argument("--report", required=True)
+    show_view = sub.add_parser("show-view")
+    show_view.add_argument("--report", required=True)
+    show_view.add_argument("--project-root", required=True)
+    begin = sub.add_parser("begin")
+    begin.add_argument("--report", required=True)
+    begin.add_argument("--task-key", required=True)
+    answer = sub.add_parser("answer")
+    answer.add_argument("--transaction", required=True)
+    answer.add_argument("--clarification-id", required=True)
+    answer.add_argument("--kind", required=True)
+    answer.add_argument("--disposition", choices=sorted(_DIRECT_ANSWER_DISPOSITIONS))
+    answer_input = answer.add_mutually_exclusive_group(required=True)
+    answer_input.add_argument("--option-number", type=int)
+    answer_input.add_argument("--value-file")
+    answer.add_argument("--rationale-file")
+    decision = sub.add_parser("plan-decision")
+    decision.add_argument("--transaction", required=True)
+    decision.add_argument("--status", choices=sorted(_PLAN_DECISION_STATUSES), required=True)
+    decision.add_argument("--implementation-option", default="")
+    decision.add_argument("--reason-file")
+    authoring = sub.add_parser("legacy-report-authoring")
+    authoring.add_argument("--transaction", required=True)
+    authoring.add_argument("--status", choices=("approved", "denied"), required=True)
+    authoring.add_argument("--reason-file", required=True)
+    sub.add_parser("finalize").add_argument("--transaction", required=True)
+    return parser
+
+
+def _write_json(value: object) -> None:
+    json.dump(value, sys.stdout, ensure_ascii=False)
+
+
+def _dispatch_command(ns: argparse.Namespace) -> None:
+    if ns.cmd in {"list", "list-view"}:
+        rows = list_awaiting_tasks(Path(ns.home), ns.project, ns.limit)
+        if ns.cmd == "list":
+            _write_json(rows)
+        else:
+            sys.stdout.write(format_list_view(rows))
+    elif ns.cmd == "show":
+        _write_json(show_open_rows(Path(ns.report)))
+    elif ns.cmd == "show-view":
+        sys.stdout.write(format_show_view(Path(ns.report), Path(ns.project_root)))
+    elif ns.cmd == "begin":
+        _write_json({"transaction": begin_response(Path(ns.report), ns.task_key)})
+    elif ns.cmd == "answer":
+        answer_response(
+            ns.transaction,
+            ns.clarification_id,
+            ns.kind,
+            ns.disposition,
+            Path(ns.value_file) if ns.value_file else None,
+            Path(ns.rationale_file) if ns.rationale_file else None,
+            ns.option_number,
+        )
+        _write_json({"transaction": ns.transaction, "status": "draft"})
+    elif ns.cmd == "plan-decision":
+        set_plan_decision(
+            ns.transaction,
+            ns.status,
+            ns.implementation_option,
+            Path(ns.reason_file) if ns.reason_file else None,
+        )
+        _write_json({"transaction": ns.transaction, "status": "draft"})
+    elif ns.cmd == "legacy-report-authoring":
+        set_legacy_report_authoring(
+            ns.transaction, ns.status, Path(ns.reason_file)
+        )
+        _write_json({"transaction": ns.transaction, "status": "draft"})
+    elif ns.cmd == "finalize":
+        _write_json({"sidecar": str(finalize_response(ns.transaction))})
 
-    pl = sub.add_parser("list")
-    pl.add_argument("--home", required=True)
-    pl.add_argument("--project", required=True)
-    pl.add_argument("--limit", type=int, default=3)
-
-    ps = sub.add_parser("show")
-    ps.add_argument("--report", required=True)
-
-    pw = sub.add_parser("write")
-    pw.add_argument("--report", required=True)
-    pw.add_argument("--answers", required=True, help="JSON array of answer entries")
-    pw.add_argument(
-        "--plan-decision", default="",
-        help='JSON plan decision, e.g. {"status":"rejected","reason":"..."}')
-    pw.add_argument(
-        "--report-authoring", default="",
-        help='JSON report-authoring permission, e.g. '
-             '{"status":"approved","reason":"report-writer failed twice"}. '
-             'Only the user may grant this; the lead cannot write it for itself.')
-    pw.add_argument("--task-key", default="", help="task-key from list/show context")
-
-    ns = parser.parse_args(argv)
-    if ns.cmd == "list":
-        out = list_awaiting_tasks(Path(ns.home), ns.project, ns.limit)
-        json.dump(out, sys.stdout, ensure_ascii=False)
-        return 0
-    if ns.cmd == "show":
-        json.dump(show_open_rows(Path(ns.report)), sys.stdout, ensure_ascii=False)
-        return 0
-    if ns.cmd == "write":
-        answers = json.loads(ns.answers)
-        decision = json.loads(ns.plan_decision) if ns.plan_decision else None
-        authoring = (
-            json.loads(ns.report_authoring) if ns.report_authoring else None
-        )
-        created_at = dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-        p = write_sidecar(Path(ns.report), answers, decision, created_at,
-                          task_key=ns.task_key, report_authoring=authoring)
-        json.dump({"sidecar": str(p)}, sys.stdout, ensure_ascii=False)
-        return 0
-    return 1
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = _build_parser()
+    namespace = parser.parse_args(argv)
+    if namespace.cmd == "answer":
+        option_mode = namespace.option_number is not None
+        if option_mode and (
+            namespace.disposition is not None or namespace.rationale_file is not None
+        ):
+            parser.error(
+                "--option-number cannot be combined with --disposition or --rationale-file"
+            )
+        if not option_mode and namespace.disposition is None:
+            parser.error("--value-file requires --disposition")
+    _dispatch_command(namespace)
+    return 0
 
 
 if __name__ == "__main__":