okstra 0.59.0 → 0.60.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.59.0",
+  "version": "0.60.1",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.59.0",
-  "builtAt": "2026-06-09T01:52:37.281Z",
+  "package": "0.60.1",
+  "builtAt": "2026-06-09T04:37:38.373Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/clarification_items.py

@@ -218,3 +218,25 @@ def unresolved_approval_blockers(report_text: str) -> Optional[list[Clarificatio
         it for it in items
         if it.blocks == "approval" and it.status in UNRESOLVED_STATUSES
     ]
+
+
+# 느슨한 §1 헤딩 탐지: 엄격한 SECTION_HEADING_PATTERN 이 실패해도 이게 매칭되면
+# "§1 헤딩은 있는데 형태가 어긋나 파싱에 실패" 한 상태다. trailing 부분을 보지
+# 않으므로 앵커 변형·수동 편집·미래 렌더 변경 어디서든 헤딩의 존재만 잡는다.
+_LOOSE_SECTION_1_RE = re.compile(r"^##\s+1\.\s+Clarification Items\b", re.MULTILINE)
+
+
+def section_1_present_but_unparsed(report_text: str) -> bool:
+    """§1 헤딩이 느슨 탐지엔 잡히지만 엄격 SECTION_HEADING_PATTERN 에는 매칭하지
+    못하는 경우 True — 헤딩 형태가 어긋나(앵커·포맷 drift) §1 슬라이스 자체가
+    실패하는 상태다.
+
+    이때 ``_section_1_slice`` 가 None 을 반환해 parse 가 통째로 None 이 되고 승인
+    게이트가 "schema 없음 → soft-pass" 로 조용히 열린다. §1 앵커 버그가 정확히 이
+    메커니즘으로 터졌다. 헤딩 자체가 없는 legacy 리포트(둘 다 불매칭)와, 엄격
+    매칭에 성공하는 정상 헤딩(테이블이 없는 emptyState placeholder 포함)은 False —
+    placeholder 는 헤딩이 멀쩡하므로 fail-closed 로 오인하지 않는다. 정규식만 넓혀 온
+    과거 수정과 달리, 이 판별은 "헤딩 형태 drift" 자체를 차단해 재발 클래스를 닫는다."""
+    if SECTION_HEADING_PATTERN.search(report_text):
+        return False
+    return bool(_LOOSE_SECTION_1_RE.search(report_text))

package/runtime/python/okstra_ctl/render_final_report.py

@@ -50,6 +50,7 @@ from jinja2 import ChainableUndefined, Environment, FileSystemLoader
 
 from okstra_ctl.final_report_schema import SchemaError, load_schema, validate as schema_validate
 from okstra_ctl.i18n import I18nError, SUPPORTED_LANGS, load_dictionary, make_jinja_global
+from okstra_ctl.models import UnknownModelError, resolve_model_metadata
 
 
 DEFAULT_TEMPLATE_REL = ("templates", "reports", "final-report.template.md")
@@ -351,6 +352,44 @@ def _enforce_schema(data: dict) -> None:
         )
 
 
+# 일반 alias('opus'/'sonnet'/'haiku')가 런타임에 해소되는, okstra 가 아는 최신
+# 구체버전 — final-report '표시 전용'. 실행 인자(execution value)는 바꾸지 않으며
+# (여전히 'opus' 가 `claude --model` 로 전달됨), 이 매핑은 보고서에서 "어느
+# 구체버전 계열로 돌았는지" 가독성만 준다. CLI 가 실제 고른 버전과 다를 수
+# 있으나 표시이므로 실행에는 무해하다. 새 버전이 나오면 여기만 갱신한다.
+_DISPLAY_CONCRETE_CLAUDE = {
+    "opus": "claude-opus-4-7",
+    "sonnet": "claude-sonnet-4-6",
+    "haiku": "claude-haiku-4-5",
+}
+
+
+def _model_detail(display: Any) -> str:
+    """모델 display alias(예: 'opus')를 'opus (claude-opus-4-7)' 형태로 상세화한다.
+
+    lead·report-writer 헤더 모델은 항상 claude provider 다. 구체 alias('opus-4-7'
+    등)는 claude 매핑의 실행 ID 를, 일반 alias('opus' 등)는 표시 전용
+    `_DISPLAY_CONCRETE_CLAUDE` 의 권장 구체버전을 병기한다. 어느 쪽에도 없는 값
+    (이미 실행 ID 이거나 'default' 등)은 원본을 그대로 돌려준다. 바깥 백틱은
+    템플릿이 감싸므로 여기서는 넣지 않는다."""
+    text = str(display or "").strip()
+    if not text:
+        return text
+    try:
+        meta = resolve_model_metadata(
+            provider="claude", raw_value=text,
+            default_display=text, default_execution="",
+        )
+    except UnknownModelError:
+        meta = None
+    if meta and meta.execution and meta.execution != text:
+        return f"{text} ({meta.execution})"
+    concrete = _DISPLAY_CONCRETE_CLAUDE.get(text.lower())
+    if concrete:
+        return f"{text} ({concrete})"
+    return text
+
+
 def _build_environment(template_dir: Path) -> Environment:
     # ChainableUndefined lets optional fields (e.g.
     # ``clarificationCarryIn``, ``ticketCoverage.omit``) silently evaluate
@@ -370,6 +409,7 @@ def _build_environment(template_dir: Path) -> Environment:
     env.filters["format_duration_ms"] = _format_duration_ms
     env.filters["yaml_scalar"] = _yaml_scalar
     env.filters["yaml_inline_list"] = _yaml_inline_list
+    env.filters["model_detail"] = _model_detail
     return env
 
 

package/runtime/python/okstra_ctl/run.py

@@ -28,7 +28,10 @@ from pathlib import Path
 
 from okstra_project import project_json_path, upsert_project_json
 from .analysis_packet import build_analysis_packet
-from .clarification_items import unresolved_approval_blockers
+from .clarification_items import (
+    section_1_present_but_unparsed,
+    unresolved_approval_blockers,
+)
 from .qa_commands import format_errors as _format_qa_errors, validate_qa_commands
 from .material import (
     build_analysis_material,
@@ -341,6 +344,14 @@ def _validate_approved_plan(path: str) -> None:
     # frontmatter approved == true 상태. §1 Clarification Items 의
     # Blocks=approval 행이 아직 open/answered 면 승인을 무효화한다.
     blockers = unresolved_approval_blockers(body)
+    if blockers is None and section_1_present_but_unparsed(body):
+        raise PrepareError(
+            f"approved plan has a `## 1. Clarification Items` heading but its table "
+            f"could not be parsed (heading/anchor/format drift): {path}\n"
+            "  the approval gate cannot confirm there are no unresolved "
+            "`Blocks=approval` rows, so it refuses to soft-pass. Re-render the report "
+            "with scripts/okstra-render-final-report.py so §1 matches the schema, then retry."
+        )
     if blockers:
         lines = [
             f"approved plan frontmatter has `approved: true` but §1 has {len(blockers)} "

package/runtime/python/okstra_ctl/wizard.py

@@ -31,7 +31,10 @@ from okstra_ctl.models import (
     UnknownModelError,
     resolve_model_metadata,
 )
-from okstra_ctl.clarification_items import unresolved_approval_blockers
+from okstra_ctl.clarification_items import (
+    section_1_present_but_unparsed,
+    unresolved_approval_blockers,
+)
 from okstra_ctl.pr_template import PrTemplateError, resolve_pr_template_path
 from okstra_ctl.run import (
     APPROVED_FRONTMATTER_PATTERN,
@@ -455,6 +458,13 @@ def _validate_approved_plan(path_str: str, project_root: Path) -> Path:
     # frontmatter approved == true 라도 §1 의 Blocks=approval 행이 미해결이면
     # 승인이 무효 — prepare_task_bundle 의 _validate_approved_plan 과 동일 규약.
     blockers = unresolved_approval_blockers(body)
+    if blockers is None and section_1_present_but_unparsed(body):
+        raise WizardError(
+            f"approved plan has a `## 1. Clarification Items` heading but its table "
+            f"could not be parsed (heading/anchor/format drift): {p}\n"
+            "  the approval gate cannot confirm there are no unresolved "
+            "`Blocks=approval` rows — re-render the report so §1 matches the schema."
+        )
     if blockers:
         lines = [
             f"approved plan frontmatter has `approved: true` but §1 has {len(blockers)} "
@@ -716,7 +726,7 @@ def _build_task_pick(state: WizardState) -> Prompt:
     latest_key = latest.get("taskKey") or ""
     latest_suffix = t["options"].get("_LATEST_SUFFIX", "")
     options: list[Option] = []
-    for entry in tasks[:8]:
+    for entry in tasks[:16]:
         key = entry.get("taskKey") or ""
         ttype = entry.get("taskType") or ""
         phase = (entry.get("workflow") or {}).get("currentPhase") or ttype
@@ -985,11 +995,31 @@ def _submit_task_id_text(state: WizardState, value: str) -> Optional[str]:
     return f"task-id: {state.task_id}"
 
 
+def _existing_task_next_phase(state: WizardState) -> str:
+    """새 task 로 시작했더라도 입력한 task-key 가 이미 존재하면(=사실상 이어가기)
+    그 기존 manifest 의 nextRecommendedPhase 를 반환한다. 없으면 ''.
+
+    사용자가 picker 에서 기존 task-key 를 고르지 않고 new-task 흐름으로 같은
+    task-group/task-id 를 다시 입력한 경우에도 직전 phase 의 추천이 끊기지 않게
+    하는 안전장치."""
+    if not (state.project_id and state.task_group and state.task_id):
+        return ""
+    key = f"{state.project_id}:{state.task_group}:{state.task_id}"
+    root = find_task_root(Path(state.project_root), key)
+    if root is None:
+        return ""
+    workflow = (read_task_manifest(root) or {}).get("workflow") or {}
+    nxt = workflow.get("nextRecommendedPhase") or ""
+    return nxt if isinstance(nxt, str) else ""
+
+
 def _build_task_type(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "task_type")
     recommended_suffix = t["options"].get("_RECOMMENDED_SUFFIX", "")
     options: list[Option] = []
     recommended = state.task_type if not state.is_new_task else ""
+    if not recommended and state.is_new_task:
+        recommended = _existing_task_next_phase(state)
     seen: list[str] = []
     if recommended and recommended in TASK_TYPE_VALUES:
         d = dict(TASK_TYPES)[recommended]
@@ -1340,8 +1370,11 @@ def _suggest_latest_final_report(state: WizardState) -> str:
     runs_base = task_runs_dir(state.project_root, state.task_group, state.task_id)
     if not runs_base.is_dir():
         return ""
+    # run 산출물 구조는 runs/<task-type>/reports/final-report-*.md (1단계).
+    # 과거 `*/*/reports/...` (2단계) glob 은 실제 구조와 어긋나 항상 빈 결과여서
+    # clarification 단계가 직전 final-report 를 추천하지 못했다.
     candidates = [
-        p for p in runs_base.glob("*/*/reports/final-report-*.md")
+        p for p in runs_base.glob("*/reports/final-report-*.md")
         if p.is_file()
     ]
     if not candidates:
@@ -1424,11 +1457,14 @@ def _pick_snippet(value: str, style: str) -> str:
 def _build_optional_cached_pick(state: WizardState, spec: _OptionalCachedPickSpec) -> Prompt:
     suggestion = spec.suggest(state)
     t = _p(state.workspace_root, spec.prompt_key)
-    options: list[Option] = [_opt(PICK_SKIP, t["options"][PICK_SKIP])]
+    # 추천(이전 directive·siblings·최근 리포트·프로젝트 기본)을 가장 먼저 노출하고,
+    # '건너뛰기'는 중간, '직접 입력'은 항상 마지막에 둔다 (run-prompt 추천 규칙).
+    options: list[Option] = []
     if suggestion:
         snippet = _pick_snippet(suggestion, spec.snippet_style)
         options.append(_opt(spec.recommend_token, t["labels"][spec.label_key].format(snippet=snippet)))
         setattr(state, spec.cache_attr, suggestion)
+    options.append(_opt(PICK_SKIP, t["options"][PICK_SKIP]))
     options.append(_opt(PICK_TYPE_CUSTOM, t["options"][PICK_TYPE_CUSTOM]))
     return Prompt(
         step=spec.step, kind="pick",
@@ -1592,9 +1628,13 @@ def _critic_provider_label(provider: str, t: dict) -> str:
 def _build_critic_pick(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "critic_pick")
     off_label = t["options"].get("off", "off")
-    options = [_opt("off", off_label)]
-    for provider in _critic_provider_choices():
-        options.append(_opt(provider, _critic_provider_label(provider, t)))
+    # 추천(claude critic)을 가장 먼저, 'off'(critic 미사용)를 마지막에 둔다
+    # (run-prompt 추천 규칙: 추천이 항상 첫 옵션).
+    options = [
+        _opt(provider, _critic_provider_label(provider, t))
+        for provider in _critic_provider_choices()
+    ]
+    options.append(_opt("off", off_label))
     return Prompt(
         step=S_CRITIC_PICK, kind="pick",
         label=t["label"],
@@ -1671,7 +1711,10 @@ def _submit_defaults_or_custom(state: WizardState, value: str) -> Optional[str]:
     if value not in ("defaults", "customize"):
         raise WizardError(f"expected 'defaults' or 'customize', got: {value!r}")
     state.use_defaults = value == "defaults"
-    return f"customize: {'no' if state.use_defaults else 'yes'}"
+    mode = ("defaults (recommended models as-is)"
+            if state.use_defaults
+            else "customize (manual model pick)")
+    return f"model-mode: {mode}"
 
 
 def _build_workers_override(state: WizardState) -> Prompt:
@@ -1719,7 +1762,13 @@ def _submit_workers_override(state: WizardState, value: str) -> Optional[str]:
 
 
 def _model_pick(step: str, label: str, options: list[str], echo: str) -> Prompt:
-    opts = [_opt(o, o) for o in options]
+    # "default" picks the role's recommended model — leaving it here yields
+    # the SAME result as the 'Use defaults' branch. Spell that out on the
+    # label so default ↔ customize never reads as "no difference".
+    opts = [
+        _opt(o, "default (recommended model)" if o == "default" else o)
+        for o in options
+    ]
     return Prompt(step=step, kind="pick", label=label,
                   options=opts, echo_template=echo)
 
@@ -2170,14 +2219,16 @@ STEPS: list[Step] = [
                             and S_REPORT_WRITER_MODEL not in s.answered),
          build=_build_report_writer_model, submit=_submit_report_writer_model,
          owns=("report_writer_model",)),
+    # directive(이번 run 의 추가 지시)는 기본값/커스터마이즈와 무관하게 항상
+    # 묻는다 — 매 run 마다 줄 수 있는 입력이므로 'Use defaults' 분기 뒤에 숨기지
+    # 않는다. (use_defaults is not None: defaults_or_custom 답 이후에만 등장)
     Step(S_DIRECTIVE_PICK,
-         applies=lambda s: (s.use_defaults is False
-                            and S_DIRECTIVE_PICK not in s.answered),
+         applies=lambda s: (S_DIRECTIVE_PICK not in s.answered
+                            and s.use_defaults is not None),
          build=_build_directive_pick, submit=_submit_directive_pick,
          owns=("directive", "directive_pending_text")),
     Step(S_DIRECTIVE,
-         applies=lambda s: (s.use_defaults is False
-                            and s.directive_pending_text
+         applies=lambda s: (s.directive_pending_text
                             and S_DIRECTIVE not in s.answered),
          build=_build_directive, submit=_submit_directive,
          owns=("directive", "directive_pending_text")),
@@ -2192,14 +2243,19 @@ STEPS: list[Step] = [
                             and S_RELATED_TASKS not in s.answered),
          build=_build_related_tasks, submit=_submit_related_tasks,
          owns=("related_tasks_raw", "related_tasks_pending_text")),
+    # clarification(직전 phase final-report 입력)은 customize 전용이 아니다.
+    # 이어가기에 필수인 직전 final-report 가 존재하면 use_defaults 와 무관하게
+    # 입력 기회를 노출한다. (과거: use_defaults 게이트 뒤에 숨어 "Use defaults"
+    # 를 고르면 직전 리포트가 통째로 누락됐다.)
     Step(S_CLARIFICATION_PICK,
-         applies=lambda s: (s.use_defaults is False
-                            and S_CLARIFICATION_PICK not in s.answered),
+         applies=lambda s: (S_CLARIFICATION_PICK not in s.answered
+                            and s.use_defaults is not None
+                            and (s.use_defaults is False
+                                 or bool(_suggest_latest_final_report(s)))),
          build=_build_clarification_pick, submit=_submit_clarification_pick,
          owns=("clarification_response_path", "clarification_pending_text")),
     Step(S_CLARIFICATION,
-         applies=lambda s: (s.use_defaults is False
-                            and s.clarification_pending_text
+         applies=lambda s: (s.clarification_pending_text
                             and S_CLARIFICATION not in s.answered),
          build=_build_clarification, submit=_submit_clarification,
          owns=("clarification_response_path", "clarification_pending_text")),
@@ -2469,6 +2525,7 @@ def confirmation_block(state: WizardState) -> str:
     lines: list[str] = [header]
     lines.append(f"  task-type     : {state.task_type}")
     lines.append(f"  task-key      : {state.task_group}/{state.task_id}")
+    lines.append(f"  brief         : {state.brief_path or '(none)'}")
     if state.reuse_worktree:
         lines.append("  base-ref      : (reusing existing worktree)")
     else:
@@ -2491,6 +2548,8 @@ def confirmation_block(state: WizardState) -> str:
     if state.report_writer_model:
         lines.append(f"  report-writer : {state.report_writer_model}")
     lines.append(f"  directive     : {state.directive or '(none)'}")
+    if state.related_tasks_raw:
+        lines.append(f"  related-tasks : {state.related_tasks_raw}")
     if state.task_type in ("requirements-discovery", "error-analysis", "implementation-planning", "final-verification"):
         lines.append(f"  critic        : {state.critic or '(off)'}")
     if state.task_type in _STAGE_SCOPED_TASK_TYPES:

package/runtime/schemas/final-report-v1.0.schema.json

@@ -536,7 +536,10 @@
               "type": "array",
               "items": { "$ref": "#/$defs/DiffFileRow" }
             }
-          }
+          },
+          "$comment": "rawStat(git diff --stat 원문)이 비어있지 않으면(=변경 있음) files 표는 최소 1행이어야 한다. 변경을 stat 으로는 보고하면서 files 표를 비워 미선언-surface conformance 게이트를 우회하는 fail-open(SUSP-1)을 차단. 0파일 변경은 rawStat 이 빈 문자열이라 허용된다.",
+          "if": { "required": ["rawStat"], "properties": { "rawStat": { "minLength": 1 } } },
+          "then": { "properties": { "files": { "minItems": 1 } } }
         },
         "outOfPlanEdits": {
           "type": "array",

package/runtime/templates/reports/final-report.template.md

@@ -26,10 +26,11 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 - Created at: {{ header.createdAt }}
 - Task Key: {{ header.taskKey }}
 - Task Type: {{ header.taskType }}
-- Report Owner: `{{ header.reportOwner }}`
+- Report Owner: `{{ header.reportOwner }}` (model: `{{ header.leadModel | model_detail }}`)
 - Report Author: `{{ header.reportAuthor }}`
-- Lead Model: `{{ header.leadModel }}`
-- Okstra Version: `{{ header.okstraVersion }}`
+- Lead Model: `{{ header.leadModel | model_detail }}`
+{% for row in followUpTasks if row.origin == 'phase-continuation' %}{% if loop.first %}- Next Step: run `/okstra-run`, select task `{{ header.taskKey }}`, choose task-type `{{ row.suggestedTaskType }}`
+{% endif %}{% endfor %}- Okstra Version: `{{ header.okstraVersion }}`
 
 ## Verdict Card
 

package/runtime/validators/validate-implementation-plan-stages.py

@@ -13,9 +13,6 @@ from pathlib import Path
 from typing import List, Tuple
 
 STAGE_MAP_HEADING = re.compile(r"^##\s+5\.5\s+Stage\s+Map\b", re.M)
-STAGE_SECTION = re.compile(
-    r"^##\s+5\.5\.(\d+)\s+Stage\s+\1\s*:\s*(.+)$", re.M
-)
 REQUIRED_SUBSECTIONS = (
     "Carry-In",
     "Stepwise Execution Order",

package/runtime/validators/validate-report-views.py

@@ -29,7 +29,10 @@ SCRIPTS_DIR = REPO_ROOT / "scripts"
 if str(SCRIPTS_DIR) not in sys.path:
     sys.path.insert(0, str(SCRIPTS_DIR))
 
-from okstra_ctl.clarification_items import parse_clarification_items  # noqa: E402
+from okstra_ctl.clarification_items import (  # noqa: E402
+    parse_clarification_items,
+    section_1_present_but_unparsed,
+)
 from okstra_ctl.report_views import (  # noqa: E402
     extract_html_digest,
     source_digest,
@@ -80,6 +83,14 @@ def validate(report_path: Path) -> list[str]:
 
     md = report_path.read_text(encoding="utf-8")
     html_path = report_path.with_name(report_path.stem + ".html")
+    # §1 헤딩이 있는데 파싱이 실패하면 md_ids 가 빈 []이 되어 "clarification 없음
+    # → skip" 으로 흘러 HTML form parity 게이트가 조용히 열린다. fail-closed.
+    if section_1_present_but_unparsed(md):
+        return [
+            "final-report has a `## 1. Clarification Items` heading but its table "
+            "could not be parsed (heading/anchor/format drift) — cannot verify HTML "
+            "form parity. Re-render the report so §1 matches the schema."
+        ]
     md_ids = _md_response_ids(md)
 
     # (1) sibling artifact exists — conditional on §1 clarification rows.

package/runtime/validators/validate-run.py

@@ -1125,13 +1125,22 @@ def _extract_final_verdict_token(content: str) -> str | None:
     return match.group("value")
 
 
+# 렌더러는 ID 정의 셀(`<a id="r-001"></a>R-001`)에도 스크롤 앵커를 넣는다.
+# 셀 정규화 때 그 빈 앵커를 벗겨야 ID 컬럼이 bare 토큰으로 읽힌다
+# (clarification_items._CELL_ANCHOR_RE 와 동형).
+_CELL_ANCHOR_RE = re.compile(r'<a id="[^"]*"></a>')
+
+
 def _split_markdown_row(line: str) -> list[str]:
     stripped = line.strip()
     if stripped.startswith("|"):
         stripped = stripped[1:]
     if stripped.endswith("|"):
         stripped = stripped[:-1]
-    return [cell.strip().strip("`").strip() for cell in stripped.split("|")]
+    return [
+        _CELL_ANCHOR_RE.sub("", cell).strip().strip("`").strip()
+        for cell in stripped.split("|")
+    ]
 
 
 def _is_markdown_separator(line: str) -> bool: