okstra 0.154.0 → 0.154.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.154.0",
+  "version": "0.154.2",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.154.0",
-  "builtAt": "2026-08-05T16:08:35.394Z",
+  "package": "0.154.2",
+  "builtAt": "2026-08-05T18:59:33.609Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/clarification_items.py

@@ -395,11 +395,39 @@ def scan_clarification_blockers(
     report_path: Path, blocking_values: frozenset[str]
 ) -> ClarificationScan:
     """Shared fail-closed clarification walk for both gates above — schema-v2
-    reads its rows from the data sibling, schema-v1 from the §1 table."""
+    reads its rows from the data sibling, schema-v1 from the §1 table, and the
+    user's `user-responses/` sidecar outranks whatever the report says about
+    those rows."""
     v2_scan = _scan_v2_blockers(report_path, blocking_values)
-    if v2_scan is not None:
-        return v2_scan
-    return scan_section_1_blockers(_read_report_text(report_path), blocking_values)
+    scan = (
+        v2_scan if v2_scan is not None
+        else scan_section_1_blockers(_read_report_text(report_path), blocking_values)
+    )
+    return _resolve_blockers_answered_by_user(report_path, scan)
+
+
+def _resolve_blockers_answered_by_user(
+    report_path: Path, scan: ClarificationScan
+) -> ClarificationScan:
+    """사용자가 사이드카로 답한 행을 blocker 에서 뺀 스캔.
+
+    답의 정본은 사용자의 `user-responses/` 사이드카다. 리포트의 `Status` 는 그
+    run 이 스스로 적어둔 값이고, 답이 사이드카로만 들어오는 경로(HTML 뷰의
+    `Export user response`, `okstra user-response write`)에서는 갱신되지
+    않는다 — 게이트가 리포트만 보면 사용자가 답을 다 채운 뒤에도 같은 항목이
+    영원히 미해결로 남아 다음 phase 를 막는다.
+
+    fail-closed 는 그대로다: 행 자체를 못 읽은 스캔(`unreadable_reason`)은
+    어떤 id 가 blocker 인지 모르는 상태이므로 사이드카로 덮지 않는다.
+    """
+    if scan.unreadable_reason is not None or not scan.blockers:
+        return scan
+    answers = sidecar_answers(report_path)
+    if not answers:
+        return scan
+    return ClarificationScan(
+        [b for b in scan.blockers if b.row_id not in answers], None
+    )
 
 
 def scan_section_1_blockers(
@@ -587,11 +615,20 @@ def _sidecars_for_attachment(source: Path) -> list[Path]:
     return sorted([*ordinary, *selected])
 
 
-def _sidecar_answers(source: Path) -> dict[str, str]:
+def sidecar_answers(source: Path) -> dict[str, str]:
     """`user-responses/` 사이드카들의 답변을 `{clarification-id: value}` 로 모은다.
 
-    같은 id 가 여러 사이드카에 나오면 이름순 마지막(최신 seq)이 이긴다. `value`
-    가 빈 항목은 담지 않는다. `user_response` 를 지연 import 해 순환 참조를 피한다.
+    사용자가 답한 항목이 무엇인지 아는 단일 참조점 — carry-in 병합도, 승인
+    게이트도, 스킬의 열린 항목 목록도 전부 이 한 곳을 본다.
+
+    `disposition` 이 `answer` 인 항목만 답으로 센다. `reframe` 은 "다음 run 에서
+    다시 물어달라" 이지 답이 아니므로(`skills/okstra-user-response/SKILL.md` 의
+    "A reframe is not an answer") 답 집합에서 빠져야 게이트가 그 항목을 계속
+    미해결로 잡는다.
+
+    같은 id 가 여러 사이드카에 나오면 이름순 마지막(최신 seq)이 이긴다 — 최신이
+    reframe 이거나 값이 비면 앞선 답을 지운다. 그래야 답을 물렀을 때 그 항목이
+    미해결로 돌아온다. `user_response` 를 지연 import 해 순환 참조를 피한다.
     """
     from okstra_ctl.user_response import parse_user_response_entries
 
@@ -600,8 +637,10 @@ def _sidecar_answers(source: Path) -> dict[str, str]:
         for entry in parse_user_response_entries(
             sidecar.read_text(encoding="utf-8")
         ):
-            if entry.value:
+            if entry.value and entry.disposition == "answer":
                 answers[entry.response_id] = entry.value
+            else:
+                answers.pop(entry.response_id, None)
     return answers
 
 
@@ -644,7 +683,7 @@ def clarification_response_with_sidecars(source: Path) -> str:
     """
     text = source.read_text(encoding="utf-8")
     section = attached_user_responses_section(source)
-    answers = _sidecar_answers(source)
+    answers = sidecar_answers(source)
     body = _clarification_carry_body(source, text, answers)
     if not section:
         return body
@@ -750,9 +789,13 @@ def _locate_user_input_column(lines: list[str]) -> tuple[int, int]:
 
 
 def _reconcile_row(line: str, ui_col: int, answers: dict[str, str]) -> str:
-    """답이 있고 open/answered 이며 `User input` 칸이 빈 행이면 답을 채우고 Status 를
-    resolved 로 바꾼 줄을, 그 외에는 원본 줄을 그대로 돌려준다. 이미 채워진 칸은
-    표에 든 값이 정본이므로 덮어쓰지 않는다.
+    """답이 있고 open/answered 인 행이면 `User input` 칸을 그 답으로 채우고 Status 를
+    resolved 로 바꾼 줄을, 그 외에는 원본 줄을 그대로 돌려준다.
+
+    칸에 이미 값이 있어도 사용자의 사이드카 답이 이긴다. 그 칸을 채우는 것은
+    run 자신(직전 렌더가 옮겨 적은 값)이고, 사용자가 나중에 답을 바꾸면 둘이
+    갈라진다 — 사용자가 쓴 쪽을 정본으로 삼지 않으면 run 이 자기가 적어둔 값으로
+    계속 되돌아간다.
 
     판정은 앵커/백틱을 벗긴 셀(`_split_pipe_row`)로 — 그래야 `_meta_id` 가 스크롤
     앵커의 소문자 slug 대신 진짜 대문자 ID 를 읽는다. 재조립은 원본 셀
@@ -764,7 +807,7 @@ def _reconcile_row(line: str, ui_col: int, answers: dict[str, str]) -> str:
     if item.status not in UNRESOLVED_STATUSES:
         return line
     raw = split_pipe_row(line)
-    if not (0 <= ui_col < len(raw) and raw[ui_col] == ""):
+    if not 0 <= ui_col < len(raw):
         return line
     raw[ui_col] = answers[item.row_id]
     raw[0] = _STATUS_RESOLVE_RE.sub(r"\1resolved", raw[0])
@@ -772,7 +815,7 @@ def _reconcile_row(line: str, ui_col: int, answers: dict[str, str]) -> str:
 
 
 def _reconcile_user_input(section: str, answers: dict[str, str]) -> str:
-    """§1 표에서 사이드카 답이 있는 미해결 행의 빈 `User input` 칸을 답으로 채우고
+    """§1 표에서 사이드카 답이 있는 미해결 행의 `User input` 칸을 답으로 채우고
     Status 를 resolved 로 바꾼 §1 본문을 돌려준다.
 
     답의 정본 위치를 §1 표 안으로 옮긴다 — 표만 읽는 승인 게이트·프롬프트

package/runtime/python/okstra_ctl/report_html/render.py

@@ -24,6 +24,7 @@ from .filters import (
     paragraphs,
 )
 from .models import HtmlRunMeta
+from .report_index import inject_report_index
 from .router import HtmlRenderError, resolve_html_route
 
 
@@ -133,7 +134,8 @@ def render_v2_html_view(
     # threading the index through every macro and call site.
     anchors = anchor_index(data)
     chrome = load_dictionary(lang, HTML_DICTIONARY_REL)
-    env.globals["t"] = make_jinja_global(chrome)
+    translate = make_jinja_global(chrome)
+    env.globals["t"] = translate
     env.filters["code_evidence"] = code_evidence
     env.filters["enum_label"] = lambda value, vocabulary: enum_label(value, vocabulary, chrome)
     env.filters["enum_legend"] = lambda vocabulary: enum_legend(vocabulary, chrome)
@@ -154,7 +156,10 @@ def render_v2_html_view(
         "js": response_js + "\n" + base_js,
     }
     output_path = _html_path(data_path)
-    output_path.write_text(env.get_template(route.template_name).render(**context), encoding="utf-8")
+    document = env.get_template(route.template_name).render(**context)
+    output_path.write_text(
+        inject_report_index(document, label=translate("base.contents")), encoding="utf-8"
+    )
     if context["clarificationItems"]:
         # The footer tells the reader to drop the exported file here, so the
         # directory has to exist before they go looking for it.

package/runtime/python/okstra_ctl/report_html/report_index.py

@@ -0,0 +1,75 @@
+"""Build the reader's index that heads the rendered report.
+
+The index is derived from the rendered document instead of being declared in
+each task template. A template that gains a section gets an index entry with
+it, and there is no second list to keep in step.
+
+Anchors come from the id a section already carries or from its
+``data-report-section`` slug — never from the heading text, which changes with
+the report language and would move every link with it.
+"""
+from __future__ import annotations
+
+import re
+
+# Every section of the human view opens with its own h2. A block that does not
+# is not a place the reader navigates to, so it stays out of the index.
+_SECTION_HEAD_RE = re.compile(
+    r'<section\b(?P<attrs>[^>]*)>(?P<heading_open>\s*<h2[^>]*>)(?P<title>.*?)</h2>',
+    re.DOTALL,
+)
+_MAIN_OPEN_RE = re.compile(r"<main\b[^>]*>")
+_ID_RE = re.compile(r'\bid="([^"]+)"')
+_SLUG_RE = re.compile(r'\bdata-report-section="([^"]+)"')
+_TAG_RE = re.compile(r"<[^>]+>")
+
+INDEX_TITLE_ID = "report-index-title"
+
+
+def _heading_text(title_markup: str) -> str:
+    """The heading's words without the markup a link cannot carry."""
+    return " ".join(_TAG_RE.sub("", title_markup).split())
+
+
+def inject_report_index(document: str, *, label: str) -> str:
+    """Return ``document`` with a section index at the top of ``<main>``.
+
+    Sections that lack both an id and a slug are skipped rather than given a
+    generated anchor: a link whose target moves between renders is worse than
+    an entry the reader never had.
+    """
+    opening = _MAIN_OPEN_RE.search(document)
+    if opening is None:
+        return document
+    head, body = document[: opening.end()], document[opening.end() :]
+    entries: list[tuple[str, str]] = []
+
+    def _anchor_section(match: re.Match[str]) -> str:
+        attrs = match.group("attrs")
+        existing = _ID_RE.search(attrs)
+        if existing:
+            anchor = existing.group(1)
+        else:
+            slug = _SLUG_RE.search(attrs)
+            if slug is None:
+                return match.group(0)
+            anchor = f"section-{slug.group(1)}"
+            # Last, not first: templates lead a section with the attribute the
+            # tests and the validator select it by.
+            attrs = f'{attrs} id="{anchor}"'
+        entries.append((anchor, _heading_text(match.group("title"))))
+        return f'<section{attrs}>{match.group("heading_open")}{match.group("title")}</h2>'
+
+    body = _SECTION_HEAD_RE.sub(_anchor_section, body)
+    if not entries:
+        return document
+    items = "".join(
+        f'<li><a href="#{anchor}">{text}</a></li>' for anchor, text in entries
+    )
+    index = (
+        f'<nav class="report-index" aria-labelledby="{INDEX_TITLE_ID}">'
+        f'<h2 id="{INDEX_TITLE_ID}">{label}</h2>'
+        f"<ol>{items}</ol>"
+        "</nav>"
+    )
+    return f"{head}\n{index}{body}"

package/runtime/python/okstra_ctl/user_response.py

@@ -27,6 +27,7 @@ from okstra_ctl.clarification_items import (
     read_clarification_rows,
     scan_open_user_input,
     section_1_present_but_unparsed,
+    sidecar_answers,
     _section_1_slice,
 )
 
@@ -545,10 +546,13 @@ def resolve_refs(report_text: str, refs: list[str]) -> list[dict]:
 
 def show_open_rows(report_path: Path) -> dict:
     text = report_path.read_text(encoding="utf-8")
+    # 사이드카에 답이 있는 행은 사용자가 이미 답한 것이다. 리포트의 `Status` 는
+    # 그 답을 반영하지 않으므로, 이걸 빼지 않으면 스킬이 같은 질문을 다시 묻는다.
+    answered = sidecar_answers(report_path)
     rows = []
     for r in read_clarification_rows(report_path):
         it = r["item"]
-        if it.status not in ("open", "answered"):
+        if it.status not in ("open", "answered") or it.row_id in answered:
             continue
         statement, expected = r["statement"], r["expected_form"]
         refs = sorted(set(_SECTION_REF_RE.findall(statement + " " + expected)))

package/runtime/templates/reports/html/assets/base.css

@@ -16,6 +16,13 @@ main { display: grid; gap: 1rem; padding-bottom: 3rem; }
 section { padding: 1.4rem; border: 1px solid color-mix(in srgb, CanvasText 14%, transparent); border-radius: 16px; background: color-mix(in srgb, Canvas 94%, CanvasText 6%); }
 h2 { margin-top: 0; font-size: 1.45rem; }
 h3 { margin-bottom: .35rem; }
+/* The report opens with what it holds. It scrolls away with the rest rather
+   than sticking: on a phone a pinned index of a dozen sections is the page. */
+nav.report-index { padding: 1.2rem 1.4rem; border: 1px solid color-mix(in srgb, CanvasText 14%, transparent); border-radius: 16px; background: color-mix(in srgb, Canvas 94%, CanvasText 6%); }
+nav.report-index h2 { font-size: .82rem; text-transform: uppercase; letter-spacing: .08em; color: GrayText; margin-bottom: .6rem; }
+nav.report-index ol { margin: 0; padding-left: 1.4rem; columns: 2; column-gap: 2.5rem; }
+nav.report-index li { margin: .2em 0; break-inside: avoid; }
+nav.report-index a { color: inherit; }
 /* One card per row. Fitting three across left each body about sixteen
    characters wide — a third of what reads comfortably — and turned every card
    into a narrow vertical strip. These carry paragraphs, not labels. */
@@ -92,6 +99,6 @@ button:focus-visible { outline: 2px solid Highlight; outline-offset: 2px; }
 button[data-action="export-user-response"] { background: Highlight; border-color: Highlight; color: HighlightText; font-weight: 600; }
 button[data-action="export-user-response"]:hover { background: color-mix(in srgb, Highlight 82%, CanvasText); }
 /* A seven-column table needs 42em of floor, more than a phone can give. */
-@media (max-width: 640px) { section { padding: 1rem; } .visualization { display: none; } th, td { min-width: 4.5em; } }
+@media (max-width: 640px) { section { padding: 1rem; } .visualization { display: none; } th, td { min-width: 4.5em; } nav.report-index ol { columns: 1; } }
 @media print { .skip-link, script { display: none !important; } body { color: #000; background: #fff; } section { break-inside: avoid; border-color: #bbb; } .visualization-fallback { display: table; } }
 code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .9em; padding: .1em .3em; border-radius: 4px; background: color-mix(in srgb, CanvasText 8%, Canvas); }

package/runtime/templates/reports/html/i18n/en.json

@@ -72,6 +72,7 @@
   },
   "base": {
     "skip-to-report-content": "Skip to report content",
+    "contents": "Contents",
     "task": "Task",
     "task-key": "Task key",
     "written": "Written",
@@ -104,7 +105,9 @@
       "export-my-answers": "Export my answers",
       "at-the-foot-of-the-page": "at the foot of the page.",
       "answer-as": "Answer as",
-      "questions-waiting-on-you": "Questions waiting on you"
+      "questions-waiting-on-you": "Questions waiting on you",
+      "count-questions-waiting-on-you": "{count} questions waiting on you",
+      "your-answer-to-id": "Your answer to {id}"
     },
     "visualizations": {
       "component": "Component",

package/runtime/templates/reports/html/i18n/ko.json

@@ -72,6 +72,7 @@
   },
   "base": {
     "skip-to-report-content": "리포트 본문으로 건너뛰기",
+    "contents": "목차",
     "task": "태스크",
     "task-key": "태스크 키",
     "written": "작성",
@@ -104,7 +105,9 @@
       "export-my-answers": "내 답변 내보내기",
       "at-the-foot-of-the-page": "버튼을 누르세요.",
       "answer-as": "답변 형식",
-      "questions-waiting-on-you": "답변을 기다리는 질문"
+      "questions-waiting-on-you": "답변을 기다리는 질문",
+      "count-questions-waiting-on-you": "답변을 기다리는 질문 {count}건",
+      "your-answer-to-id": "{id}에 대한 답변"
     },
     "visualizations": {
       "component": "구성 요소",

package/runtime/templates/reports/html/macros/forms.html

@@ -32,15 +32,15 @@
 
 {% macro clarification_responses(items) -%}
 {% if items %}
-<section class="clarification-responses" aria-label="{{ t('macros.forms.questions-waiting-on-you') }}">
-  <h2>{{ items | length }} questions waiting on you</h2>
+<section class="clarification-responses" data-report-section="clarification-responses" aria-label="{{ t('macros.forms.questions-waiting-on-you') }}">
+  <h2>{{ t('macros.forms.count-questions-waiting-on-you') | replace('{count}', items | length) }}</h2>
   <p class="clarification-lede">{{ t('macros.forms.the-code-alone-could-not-settle-these-fill-i') }} <strong>{{ t('macros.forms.export-my-answers') }}</strong> {{ t('macros.forms.at-the-foot-of-the-page') }}</p>
   {% for row in items %}
   <article class="clarification-item" id="id-{{ row.id }}" data-response-id="{{ row.id }}" data-kind="{{ row.kind }}">
     <p class="eyebrow">{{ row.id }} · {{ row.kind }}</p>
     {{ row.statement | paragraphs }}
     <dl class="clarification-expected"><dt>{{ t('macros.forms.answer-as') }}</dt><dd>{{ row.expectedForm | inline_code }}</dd></dl>
-    <label for="response-{{ row.id }}">Your answer to {{ row.id }}</label>
+    <label for="response-{{ row.id }}">{{ t('macros.forms.your-answer-to-id') | replace('{id}', row.id) }}</label>
     <textarea id="response-{{ row.id }}" data-response-id="{{ row.id }}" rows="4">{{ row.userInput | default('') }}</textarea>
   </article>
   {% endfor %}