okstra 0.144.0 → 0.146.0

package/runtime/python/okstra_ctl/path_hints.py

@@ -188,6 +188,7 @@ def _hydrate_active_run(ctx: Mapping[str, str]) -> dict[str, str]:
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
         "promptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
         "finalReportPath": ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
+        "convergenceStatePath": ctx.get("CONVERGENCE_STATE_RELATIVE_PATH", ""),
         "finalStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
         "validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
         "resumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
@@ -430,6 +431,7 @@ def _run_files(
         "team_state": run_state / f"team-state{suffixes['state']}.json",
         "active_run_context": run_state / f"active-run-context{suffixes['state']}.json",
         "lead_events": run_state / f"lead-events-{task_type_segment}-{sequences['state']}.jsonl",
+        "convergence_state": run_state / f"convergence-{task_type_segment}-{sequences['state']}.json",
         "claude_resume_command": run_sessions / f"claude-resume{suffixes['sessions']}.sh",
         "claude_worker_result": worker_results / f"claude-worker{suffixes['worker_results']}.md",
         "codex_worker_result": worker_results / f"codex-worker{suffixes['worker_results']}.md",
@@ -540,6 +542,7 @@ def _absolute_run_fields(paths: Mapping[str, Any]) -> dict[str, str]:
         "RUN_CONTEXT_FILE": str(paths["run_context_file"]),
         "RUN_PROMPT_SNAPSHOT_FILE": str(paths["run_prompt_snapshot"]),
         "FINAL_REPORT_PATH": str(paths["final_report"]),
+        "CONVERGENCE_STATE_PATH": str(paths["convergence_state"]),
         "FINAL_STATUS_PATH": str(paths["final_status"]),
         "TEAM_STATE_PATH": str(paths["team_state"]),
         "ACTIVE_RUN_CONTEXT_PATH": str(paths["active_run_context"]),
@@ -629,6 +632,9 @@ def _relative_file_fields(project_root: Path, paths: Mapping[str, Any]) -> dict[
         "ANTIGRAVITY_WORKER_PROMPT_RELATIVE_PATH": _rel(project_root, paths["antigravity_worker_prompt"]),
         "REPORT_WRITER_WORKER_PROMPT_RELATIVE_PATH": _rel(project_root, paths["report_writer_worker_prompt"]),
         "FINAL_REPORT_RELATIVE_PATH": _rel(project_root, paths["final_report"]),
+        "CONVERGENCE_STATE_RELATIVE_PATH": _rel(
+            project_root, paths["convergence_state"]
+        ),
         "FINAL_STATUS_RELATIVE_PATH": _rel(project_root, paths["final_status"]),
         "TEAM_STATE_RELATIVE_PATH": _rel(project_root, paths["team_state"]),
         "ACTIVE_RUN_CONTEXT_RELATIVE_PATH": _rel(project_root, paths["active_run_context"]),

package/runtime/python/okstra_ctl/paths.py

@@ -66,19 +66,6 @@ def _newest_report(reports_dir: Path) -> Optional[Path]:
     return max(found, key=lambda p: (p.stat().st_mtime, p.name))
 
 
-def _report_dirs(type_dir: Path, include_stages: bool) -> list[Path]:
-    """한 task-type 의 report 디렉터리들. flat 은 항상, stage-<N> 은 opt-in.
-
-    stage-isolated task-type(implementation / final-verification)만 stage 하위를
-    갖는다. `include_stages` 가 꺼져 있으면 flat `reports/` 만 돌려준다 —
-    `latest_under` 의 원래 범위이자 resume-clarification 이 의존하는 계약이다.
-    """
-    dirs = [type_dir / "reports"]
-    if include_stages and type_dir.name in _STAGED_TASK_TYPES:
-        dirs += sorted(type_dir.glob("stage-*/reports"))
-    return dirs
-
-
 def _project_root_of(task_root: Path) -> Optional[Path]:
     """canonical `<project>/.okstra/tasks/<g>/<t>` 일 때만 project root.
 
@@ -264,42 +251,19 @@ class RunRef:
         return None if best is None else cls.from_report_path(best)
 
     @classmethod
-    def latest_across(
+    def latest_under(
         cls,
-        project_root: Path,
-        task_group: str,
-        task_id: str,
+        task_root: Path,
         task_types: Optional[tuple[str, ...]] = None,
-        *,
-        include_stages: bool = False,
     ) -> Optional["RunRef"]:
-        """여러 task-type 을 가로질러 최신 final-report 를 가리키는 ref.
+        """task_root 아래 여러 task-type 을 가로질러 최신 final-report 를 찾는다.
 
         `task_types` 를 주지 않으면 runs/ 에 실제로 존재하는 모든 task-type 을
         훑는다. 비교 규칙은 `latest` 와 같다(mtime, 동률이면 basename).
 
-        `include_stages` 를 켜면 stage-isolated task-type 의 `stage-<N>/reports/`
-        도 함께 훑는다 — phase-cleanup 이 staged run 을 자동발견할 때 쓴다.
-        """
-        return cls.latest_under(
-            task_dir(project_root, task_group, task_id),
-            task_types,
-            include_stages=include_stages,
-        )
-
-    @classmethod
-    def latest_under(
-        cls,
-        task_root: Path,
-        task_types: Optional[tuple[str, ...]] = None,
-        *,
-        include_stages: bool = False,
-    ) -> Optional["RunRef"]:
-        """`latest_across` 의 task_root 진입점.
-
         task-key 단축키/오타 진단을 이미 거쳐 task_root 를 손에 쥔 호출자
         (bash resume-clarification)가 쓴다. 그 호출자는 언제나 flat 분석 phase 만
-        넘기므로 기본값(`include_stages=False`)이 그 범위를 그대로 보존한다.
+        넘기므로 stage 하위는 훑지 않는다 — flat `reports/` 고정이 그 계약이다.
         """
         runs_dir = runs_dir_of(task_root)
         if task_types is None:
@@ -308,10 +272,9 @@ class RunRef:
             task_types = tuple(sorted(p.name for p in runs_dir.iterdir() if p.is_dir()))
         candidates: list[Path] = []
         for task_type in task_types:
-            for reports_dir in _report_dirs(runs_dir / task_type, include_stages):
-                found = _newest_report(reports_dir)
-                if found is not None:
-                    candidates.append(found)
+            found = _newest_report(runs_dir / task_type / "reports")
+            if found is not None:
+                candidates.append(found)
         if not candidates:
             return None
         return cls.from_report_path(

package/runtime/python/okstra_ctl/render.py

@@ -29,6 +29,7 @@ from okstra_project.dirs import TASK_MANIFEST_FILENAME, OKSTRA_DIR_NAME, project
 # render_task_manifest 가 동일한 리스트/딕셔너리를 로컬에 중복 정의했는데,
 # 이는 silent drift 위험이 있어 SSOT import 로 통합한다.
 from . import fix_cycles
+from .analysis_inputs import ANALYSIS_TASK_TYPES
 from .paths import okstra_home
 from .lead_runtime import lead_runtime_info
 from .path_hints import compact_active_run_context, hydrate_run_context
@@ -346,6 +347,7 @@ def _active_run(ctx: dict) -> dict:
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
         "promptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
         "finalReportPath": ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
+        "convergenceStatePath": ctx.get("CONVERGENCE_STATE_RELATIVE_PATH", ""),
         "finalStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
         "validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
         "resumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
@@ -874,6 +876,45 @@ def _required_worker_roles(ctx: dict, reviewers: list[str]) -> list[dict]:
     ]
 
 
+def _reporter_confirmation_status(brief_bytes: bytes) -> str:
+    try:
+        lines = brief_bytes.decode("utf-8").splitlines()
+    except UnicodeDecodeError:
+        return ""
+    if not lines or lines[0].strip() != "---":
+        return ""
+    for line in lines[1:]:
+        if line.strip() == "---":
+            break
+        key, separator, value = line.partition(":")
+        if separator and key.strip() == "reporter-confirmations":
+            return value.strip().strip("'\"").lower()
+    return ""
+
+
+def _analysis_scope_confirmation_snapshot(ctx: dict) -> dict | None:
+    if ctx.get("TASK_TYPE") not in ANALYSIS_TASK_TYPES:
+        return None
+    brief_path = Path(ctx.get("BRIEF_FILE_PATH", ""))
+    try:
+        brief_bytes = brief_path.read_bytes() if brief_path.is_file() else None
+    except OSError:
+        brief_bytes = None
+    return {
+        "taskBriefPath": ctx.get("BRIEF_RELATIVE_PATH", ""),
+        "status": (
+            _reporter_confirmation_status(brief_bytes)
+            if brief_bytes is not None
+            else ""
+        ),
+        "briefSha256": (
+            hashlib.sha256(brief_bytes).hexdigest()
+            if brief_bytes is not None
+            else ""
+        ),
+    }
+
+
 def _derive_phase_states(existing_workflow: dict, ctx: dict) -> tuple[dict, str, str]:
     """phaseStates dict + (current_phase, current_phase_state) 를 도출한다.
 
@@ -1204,9 +1245,8 @@ def _build_convergence_block(ctx: dict) -> dict:
     - `enabled` default True
     - `maxRounds` default 1 for `requirements-discovery`, 2 otherwise
     - `verificationMode` default "lightweight"
-    - `adversarial` default True for `requirements-discovery` / `error-analysis` /
-      `implementation-planning` (forces `verificationMode` to "full-reanalysis"),
-      False otherwise
+    - `adversarial` default True for discovery, planning, and analysis task types
+      (forces `verificationMode` to "full-reanalysis"), False otherwise
     - `planBodyVerification` is implementation-planning specific; the key is
       always emitted (dead-letter on other phases) so the schema stays stable.
       Its `selfFixMaxRounds` default 3 bounds the report-writer self-fix loop
@@ -1222,7 +1262,14 @@ def _build_convergence_block(ctx: dict) -> dict:
     """
     task_type = ctx.get("TASK_TYPE", "")
     default_max_rounds = 1 if task_type == "requirements-discovery" else 2
-    adversarial_phases = {"requirements-discovery", "error-analysis", "implementation-planning"}
+    adversarial_phases = {
+        "requirements-discovery",
+        "error-analysis",
+        "implementation-planning",
+        "project-analysis",
+        "feature-analysis",
+        "change-impact-analysis",
+    }
     is_adversarial = task_type in adversarial_phases
     raw_plan_verify = (ctx.get("OKSTRA_PLAN_VERIFICATION", "") or "").strip().lower()
     plan_verify_enabled = raw_plan_verify != "false"
@@ -1257,6 +1304,20 @@ def _build_convergence_block(ctx: dict) -> dict:
 
 
 def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
+    run_manifest_file = Path(run_manifest_path)
+    existing_run_manifest = {}
+    if run_manifest_file.is_file():
+        try:
+            loaded_run_manifest = json.loads(
+                run_manifest_file.read_text(encoding="utf-8")
+            )
+            existing_run_manifest = (
+                loaded_run_manifest
+                if isinstance(loaded_run_manifest, dict)
+                else {}
+            )
+        except (OSError, json.JSONDecodeError):
+            existing_run_manifest = {}
     task_manifest_path = Path(ctx.get("TASK_MANIFEST_PATH", ""))
     task_manifest = {}
     if task_manifest_path.exists():
@@ -1329,7 +1390,16 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "expectedStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
         "activeRunContextPath": ctx.get("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", ""),
+        "convergenceStatePath": ctx.get("CONVERGENCE_STATE_RELATIVE_PATH", ""),
         "analysisPacketPath": ctx.get("ANALYSIS_PACKET_RELATIVE_PATH", ""),
+        "analysisEvidencePath": (
+            ctx.get("INSTRUCTION_SET_RELATIVE_PATH", "") + "/analysis-evidence.md"
+            if ctx.get("TASK_TYPE") in {"project-analysis", "feature-analysis", "change-impact-analysis"}
+            else ""
+        ),
+        "analysisSourceCommit": ctx.get("ANALYSIS_SOURCE_COMMIT", ""),
+        "analysisTarget": json.loads(ctx.get("ANALYSIS_TARGET_JSON", "{}")),
+        "evidenceInputs": json.loads(ctx.get("EVIDENCE_INPUTS_JSON", "[]")),
         "verificationTargetPath": ctx.get("VERIFICATION_TARGET_RELATIVE_PATH", ""),
         "verificationTargetDigest": ctx.get("VERIFICATION_TARGET_DIGEST", ""),
         "workerResultsDirectoryPath": ctx.get("WORKER_RESULTS_RELATIVE_PATH", ""),
@@ -1403,6 +1473,11 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "renderOnly": ctx.get("RENDER_ONLY", ""),
         "createdAt": ctx.get("RUN_TIMESTAMP_ISO", ""),
     }
+    scope_confirmation = existing_run_manifest.get("analysisScopeConfirmation")
+    if "analysisScopeConfirmation" not in existing_run_manifest:
+        scope_confirmation = _analysis_scope_confirmation_snapshot(ctx)
+    if scope_confirmation is not None:
+        payload["analysisScopeConfirmation"] = scope_confirmation
     if ctx.get("FIX_CYCLE_ID"):
         payload["fixCycleId"] = ctx["FIX_CYCLE_ID"]
     payload["reportContracts"] = (

package/runtime/python/okstra_ctl/render_final_report.py

@@ -67,7 +67,7 @@ class FinalReportRenderError(RuntimeError):
 
 
 def _format_int(value: Any) -> str:
-    if value is None:
+    if value is None or not isinstance(value, (str, int, float)):
         return "--"
     try:
         return f"{int(value):,}"
@@ -76,7 +76,7 @@ def _format_int(value: Any) -> str:
 
 
 def _format_usd(value: Any) -> str:
-    if value is None:
+    if value is None or not isinstance(value, (str, int, float)):
         return "--"
     try:
         return f"${float(value):.2f}"
@@ -85,7 +85,7 @@ def _format_usd(value: Any) -> str:
 
 
 def _format_duration_ms(value: Any) -> str:
-    if value is None:
+    if value is None or not isinstance(value, (str, int, float)):
         return "--"
     try:
         ms = int(value)
@@ -583,10 +583,16 @@ def resolve_report_language(data: dict, *, override: str | None) -> str:
 # through, `| length` raises on it, and both `x` and `not x` evaluate true. So a
 # template cannot test for absence at all, and the value has to arrive filled.
 _OPTIONAL_ARRAY_DEFAULTS = ("endStateCoverage",)
+_OPTIONAL_ANALYSIS_DEFAULTS = (
+    "analysisCommon",
+    "projectAnalysis",
+    "featureAnalysis",
+    "changeImpactAnalysis",
+)
 
 
 def _with_optional_defaults(data: dict) -> dict:
-    """Render context with schema-optional arrays filled in.
+    """Render context with schema-optional fields filled in.
 
     Keeps the schema field optional — an omitted `endStateCoverage` stays absent
     in data.json, which is what the run validator reads to tell a legacy brief
@@ -597,6 +603,9 @@ def _with_optional_defaults(data: dict) -> dict:
     for key in _OPTIONAL_ARRAY_DEFAULTS:
         if not isinstance(filled.get(key), list):
             filled[key] = []
+    for key in _OPTIONAL_ANALYSIS_DEFAULTS:
+        if not isinstance(filled.get(key), dict):
+            filled[key] = None
     return filled
 
 

package/runtime/python/okstra_ctl/report_views.py

@@ -108,6 +108,11 @@ class RunMeta:
     source_report: str  # relative path of the .md the HTML is derived from
 
 
+@dataclass(frozen=True)
+class AnalysisReviewContext:
+    selector_ids: tuple[str, ...]
+
+
 # task-type itself can contain hyphens (``implementation-planning``,
 # ``final-verification``, ``release-handoff``), so the filename segment
 # between ``final-report-`` and ``-<seq>.md`` is matched greedily; the
@@ -159,6 +164,7 @@ class ReportViewModel:
     sidecar_dir: str
     approval_ctx: PlanApprovalContext | None = None
     reader_ctx: ReaderDashboardContext | None = None
+    analysis_review_ctx: AnalysisReviewContext | None = None
 
 
 @dataclass(frozen=True)
@@ -179,6 +185,7 @@ def build_report_view_model(
     run_meta: RunMeta,
     approval_ctx: PlanApprovalContext | None = None,
     reader_ctx: ReaderDashboardContext | None = None,
+    analysis_review_ctx: AnalysisReviewContext | None = None,
 ) -> ReportViewModel:
     digest = source_digest(src_md)
     body_md = _strip_leading_frontmatter(src_md)
@@ -197,6 +204,7 @@ def build_report_view_model(
         sidecar_dir=f"runs/{run_meta.task_type}/user-responses/",
         approval_ctx=approval_ctx,
         reader_ctx=reader_ctx,
+        analysis_review_ctx=analysis_review_ctx,
     )
 
 
@@ -258,6 +266,7 @@ def render_report_view_model(
         f"</header>\n"
         f"<main>{_reader_dashboard(model.reader_ctx)}{model.body_html}</main>\n"
         f"{_plan_approval_section(model.approval_ctx, run_meta) if model.approval_ctx else ''}"
+        f"{_analysis_review_section(model.analysis_review_ctx) if model.analysis_review_ctx else ''}"
         f"<footer class=\"report-footer\">\n"
         f"  <button type=\"button\" data-action=\"export-user-response\">Export user response</button>\n"
         f"  <p class=\"user-response-hint\">Export 클릭 시 <code>{sidecar_name}</code> 가 다운로드됩니다 — "
@@ -288,6 +297,7 @@ def render_html(
     js: str,
     approval_ctx: PlanApprovalContext | None = None,
     reader_ctx: ReaderDashboardContext | None = None,
+    analysis_review_ctx: AnalysisReviewContext | None = None,
 ) -> str:
     """Return a single self-contained HTML document for ``src_md``.
 
@@ -300,6 +310,7 @@ def render_html(
         run_meta=run_meta,
         approval_ctx=approval_ctx,
         reader_ctx=reader_ctx,
+        analysis_review_ctx=analysis_review_ctx,
     )
     return render_report_view_model(model, css=css, js=js)
 
@@ -1021,12 +1032,56 @@ class UserResponseApproval:
     implementation_option: str = ""
 
 
+@dataclass(frozen=True)
+class UserResponseAnalysisReview:
+    status: str
+    affected_ids: tuple[str, ...] = ()
+    reason: str = ""
+    additional_evidence: str = ""
+    requested_scope_change: str = ""
+
+
+_ANALYSIS_REVIEW_STATUSES = frozenset({
+    "accepted",
+    "revision-requested",
+    "rejected",
+})
+
+
+def _quoted_sidecar_field(label: str, value: str) -> str:
+    cleaned = value.strip()
+    if not cleaned:
+        return f"- {label}:\n"
+    quoted = "".join(f"  > {line}\n" for line in cleaned.split("\n"))
+    return f"- {label}:\n{quoted}"
+
+
+def _serialize_analysis_review(review: UserResponseAnalysisReview) -> str:
+    if review.status not in _ANALYSIS_REVIEW_STATUSES:
+        raise ValueError(f"invalid ANALYSIS REVIEW status: {review.status}")
+    if review.status in {"revision-requested", "rejected"} and (
+        not review.affected_ids or not review.reason.strip()
+    ):
+        raise ValueError(
+            f"ANALYSIS REVIEW {review.status} requires Affected-IDs and Reason"
+        )
+    return (
+        "\n## ANALYSIS REVIEW\n"
+        f"- Status: {review.status}\n"
+        f"- Affected-IDs: {', '.join(review.affected_ids)}\n"
+        f"{_quoted_sidecar_field('Reason', review.reason)}"
+        f"{_quoted_sidecar_field('Additional-Evidence', review.additional_evidence)}"
+        f"{_quoted_sidecar_field('Requested-Scope-Change', review.requested_scope_change)}"
+    )
+
+
 def serialize_user_response(
     *,
     run_meta: RunMeta,
     entries: list[UserResponseEntry],
     created_at: str,
     approval: UserResponseApproval | None = None,
+    analysis_review: UserResponseAnalysisReview | None = None,
 ) -> str:
     """Return the canonical markdown text the HTML 'Export user
     response' button must produce. Used by validators to confirm that
@@ -1046,6 +1101,7 @@ def serialize_user_response(
         "# User Response\n"
     )
     has_approval = approval is not None and approval.approved
+    has_analysis_review = analysis_review is not None
     body_chunks: list[str] = []
     for e in entries:
         chunk = f"\n## {e.response_id}\n- Kind: {e.kind}\n"
@@ -1056,13 +1112,15 @@ def serialize_user_response(
         if e.rationale:
             chunk += f"- Rationale: {e.rationale.strip()}\n"
         body_chunks.append(chunk)
-    if not entries and not has_approval:
+    if not entries and not has_approval and not has_analysis_review:
         body_chunks.append("\n_(No user responses recorded.)_\n")
     if has_approval:
         chunk = "\n## APPROVAL\n- Approved: true\n"
         if approval.implementation_option:
             chunk += f"- Implementation-Option: {approval.implementation_option.strip()}\n"
         body_chunks.append(chunk)
+    if analysis_review is not None:
+        body_chunks.append(_serialize_analysis_review(analysis_review))
     return head + "".join(body_chunks)
 
 
@@ -1107,6 +1165,39 @@ def _load_report_data(src_md_path: Path) -> dict | None:
     return data if isinstance(data, dict) else None
 
 
+_ANALYSIS_DATA_KEYS = (
+    "analysisCommon",
+    "projectAnalysis",
+    "featureAnalysis",
+    "changeImpactAnalysis",
+)
+_STRUCTURED_ANALYSIS_ID_RE = re.compile(r"^[A-Z]{2}-\d{3}$")
+
+
+def _collect_structured_analysis_ids(value: object, found: set[str]) -> None:
+    if isinstance(value, dict):
+        candidate = value.get("id")
+        if isinstance(candidate, str) and _STRUCTURED_ANALYSIS_ID_RE.fullmatch(
+            candidate
+        ):
+            found.add(candidate)
+        for child in value.values():
+            _collect_structured_analysis_ids(child, found)
+    elif isinstance(value, list):
+        for child in value:
+            _collect_structured_analysis_ids(child, found)
+
+
+def analysis_review_context(src_md_path: Path) -> AnalysisReviewContext | None:
+    data = _load_report_data(src_md_path)
+    if data is None or not isinstance(data.get("analysisCommon"), dict):
+        return None
+    found: set[str] = set()
+    for key in _ANALYSIS_DATA_KEYS:
+        _collect_structured_analysis_ids(data.get(key), found)
+    return AnalysisReviewContext(selector_ids=tuple(sorted(found)))
+
+
 def plan_approval_context(
     src_md_path: Path, src_text: str
 ) -> PlanApprovalContext | None:
@@ -1298,6 +1389,35 @@ def _plan_approval_section(ctx: PlanApprovalContext, run_meta: RunMeta) -> str:
     )
 
 
+def _analysis_review_section(ctx: AnalysisReviewContext) -> str:
+    options = "".join(
+        f'<option value="{html.escape(analysis_id)}">'
+        f"{html.escape(analysis_id)}</option>"
+        for analysis_id in ctx.selector_ids
+    )
+    return (
+        '<section id="analysis-review">\n'
+        "  <h2>Analysis Review</h2>\n"
+        '  <fieldset><legend>Decision</legend>\n'
+        '    <label><input type="radio" name="analysis-review-status" '
+        'value="accepted">Accept</label>\n'
+        '    <label><input type="radio" name="analysis-review-status" '
+        'value="revision-requested">Request revision</label>\n'
+        '    <label><input type="radio" name="analysis-review-status" '
+        'value="rejected">Reject</label>\n'
+        "  </fieldset>\n"
+        '  <label>Affected IDs <select id="analysis-review-affected-ids" '
+        f'multiple>{options}</select></label>\n'
+        '  <label>Reason <textarea id="analysis-review-reason" rows="3">'
+        "</textarea></label>\n"
+        '  <label>Additional evidence <textarea id="analysis-review-evidence" '
+        'rows="3"></textarea></label>\n'
+        '  <label>Requested scope change <textarea '
+        'id="analysis-review-scope-change" rows="3"></textarea></label>\n'
+        "</section>\n"
+    )
+
+
 def render_html_view(
     src_md_path: Path,
     *,
@@ -1327,9 +1447,15 @@ def render_html_view(
             "the HTML view."
         )
     approval_ctx = plan_approval_context(src_md_path, src_text)
+    analysis_review_ctx = analysis_review_context(src_md_path)
     reader_ctx = reader_dashboard_context(src_md_path, src_text, approval_ctx)
     has_clarifications = report_has_clarification_items(src_text)
-    if not has_clarifications and approval_ctx is None and reader_ctx is None:
+    if (
+        not has_clarifications
+        and approval_ctx is None
+        and reader_ctx is None
+        and analysis_review_ctx is None
+    ):
         if html_path.is_file():
             html_path.unlink()
         return None
@@ -1340,9 +1466,14 @@ def render_html_view(
         js=js,
         approval_ctx=approval_ctx,
         reader_ctx=reader_ctx,
+        analysis_review_ctx=analysis_review_ctx,
     )
     html_path.write_text(html_text, encoding="utf-8")
-    if has_clarifications or approval_ctx is not None:
+    if (
+        has_clarifications
+        or approval_ctx is not None
+        or analysis_review_ctx is not None
+    ):
         # 사용자 확인(폼/승인)이 필요한 보고서 — Export 파일의 저장 위치를 미리
         # 만들어 사용자가 디렉토리를 만들 필요가 없게 한다 (reports/ 의 sibling).
         user_responses_dir_for_report(src_md_path).mkdir(parents=True, exist_ok=True)