okstra 0.185.0 → 0.186.0

package/runtime/python/okstra_ctl/incremental_carry.py

@@ -13,10 +13,18 @@ from .convergence_store import write_json_atomic
 from .final_report_schema import load_schema_version
 from .report_narrative import parse_narrative, writer_owned_data
 from .json_boundary import load_owned_object
+from .plan_items import (
+    PlanItemContractError,
+    content_hash,
+    extract_plan_items,
+    planning_stage_ledger,
+    reverify_item_ids,
+)
 
 
 PREP_VERDICT_RE = re.compile(r"^P-Prep-S([1-9][0-9]*)-")
 STEP_VERDICT_RE = re.compile(r"^P-Step-([1-9][0-9]*)\.")
+_CHECKLIST_ID_PREFIXES = ("P-Val-", "P-Req-", "P-Rb-")
 
 
 class CarryError(Exception):
@@ -306,6 +314,100 @@ def _plan_item_stage(item: Mapping[str, Any]) -> int | None:
     return None
 
 
+def _checklist_id(item_id: str) -> bool:
+    return item_id.startswith(_CHECKLIST_ID_PREFIXES)
+
+
+def _item_stages(item: Mapping[str, Any]) -> list[int]:
+    scope = item.get("stageScope")
+    if not isinstance(scope, list):
+        return []
+    return [
+        value for value in scope
+        if isinstance(value, int) and not isinstance(value, bool)
+    ]
+
+
+def _stamp_carried(previous: dict, current: Mapping[str, Any], prev_seq: str) -> dict:
+    carried = copy.deepcopy(previous)
+    carried["carriedForwardFromSeq"] = str(prev_seq)
+    current_hash = current.get("contentHash")
+    if isinstance(current_hash, str) and current_hash:
+        carried["verifiedContentHash"] = current_hash
+        carried["contentHash"] = current_hash
+    return carried
+
+
+def _carry_unchanged_checklists(
+    prev: Mapping[str, Any],
+    narrative: Mapping[str, Any],
+    state_items: dict[str, dict],
+    prev_items: dict[str, dict],
+    *,
+    prev_seq: str,
+    reverify_stages: set[int],
+) -> None:
+    """본문이 같은 P-Val / P-Req / P-Rb 판정을 이월한다.
+
+    단계가 없으면 매 재실행 라운드 1 큐에 남아 이미 통과한 줄이 다시 반대되고
+    새 C 가 열린다. 추출 해시가 같으면 이전 표를 가져오고, 재검증 스테이지에
+    걸린 행과 본문이 바뀐 행은 그대로 둔다.
+    """
+    try:
+        prev_extracted = {
+            item["id"]: item
+            for item in extract_plan_items(_planning(dict(prev)))
+            if isinstance(item.get("id"), str)
+        }
+        cur_extracted = {
+            item["id"]: item
+            for item in extract_plan_items(_planning(dict(narrative)))
+            if isinstance(item.get("id"), str)
+        }
+    except (CarryError, PlanItemContractError, KeyError, TypeError):
+        return
+    for item_id, current in list(state_items.items()):
+        if not _checklist_id(item_id):
+            continue
+        stages = _item_stages(current)
+        if stages and set(stages) & reverify_stages:
+            continue
+        previous = prev_items.get(item_id)
+        if previous is None:
+            continue
+        prev_row = prev_extracted.get(item_id)
+        cur_row = cur_extracted.get(item_id)
+        if prev_row is None or cur_row is None:
+            continue
+        if content_hash(prev_row) != content_hash(cur_row):
+            continue
+        state_items[item_id] = _stamp_carried(previous, current, prev_seq)
+
+
+def _recompute_dispatch_queue(
+    narrative: Mapping[str, Any],
+    state_items: dict[str, dict],
+) -> list[str]:
+    try:
+        extracted = extract_plan_items(_planning(dict(narrative)))
+    except (CarryError, PlanItemContractError, KeyError, TypeError):
+        return []
+    by_id = {
+        item["id"]: item
+        for item in extracted
+        if isinstance(item.get("id"), str)
+    }
+    previous_hashes = {
+        item_id: content_hash(by_id[item_id])
+        for item_id, row in state_items.items()
+        if row.get("carriedForwardFromSeq") and item_id in by_id
+    }
+    if not previous_hashes:
+        return []
+    ledger = planning_stage_ledger(_planning(dict(narrative)))
+    return reverify_item_ids(extracted, previous_hashes, ledger)
+
+
 def _writer_stage_rows(data: Mapping[str, Any], *, snapshot: str) -> dict[int, dict]:
     planning = _planning(dict(writer_owned_data(data)))
     return _stage_rows(planning, snapshot=snapshot)
@@ -320,7 +422,7 @@ def merge_v3_plan_state(
     carry_stages: set[int],
     reverify_stages: set[int],
 ) -> dict[str, Any]:
-    """이전 판정 중 이월 스테이지 소유분만 v3 수렴 상태에 복사한다."""
+    """이전 판정 중 이월 스테이지 소유분과 본문이 같은 체크리스트를 복사한다."""
     prev_stages = _writer_stage_rows(prev, snapshot="prior")
     cur_stages = _stage_rows(_planning(narrative), snapshot="current")
     _validate_stage_sets(prev_stages, cur_stages, carry_stages, reverify_stages)
@@ -351,9 +453,7 @@ def merge_v3_plan_state(
         for field in ("subject", "sourceSection"):
             if current.get(field) != previous.get(field):
                 raise CarryError(f"carry-owned plan item {item_id} changed {field}")
-        carried = copy.deepcopy(previous)
-        carried["carriedForwardFromSeq"] = str(prev_seq)
-        state_items[item_id] = carried
+        state_items[item_id] = _stamp_carried(previous, current, prev_seq)
 
     prior_carried_ids = {
         item_id
@@ -363,12 +463,55 @@ def merge_v3_plan_state(
     missing = sorted(prior_carried_ids - set(state_items))
     if missing:
         raise CarryError(f"current state omitted carry-owned plan items: {missing}")
-    state["planBodyVerification"]["planItems"] = [
+    _carry_unchanged_checklists(
+        prev,
+        narrative,
+        state_items,
+        prev_items,
+        prev_seq=prev_seq,
+        reverify_stages=reverify_stages,
+    )
+    pbv = state.setdefault("planBodyVerification", {})
+    pbv["planItems"] = [
         state_items[item_id] for item_id in sorted(state_items)
     ]
+    queue = _recompute_dispatch_queue(narrative, state_items)
+    if queue:
+        pbv["dispatchQueue"] = queue
     return state
 
 
+def _sync_prepared_dispatch_queue(state_path: Path, merged: Mapping[str, Any]) -> None:
+    """이월 뒤 프롬프트 큐를 상태 파일과 맞춘다.
+
+    `plan-items prompt` 는 prepare 가 쓴 `plan-items-*.json` 을 읽는다. 시드가
+    그 파일을 먼저 쓰므로, 이월이 큐를 줄인 뒤에는 형제 파일을 같이 고쳐야
+    워커가 이미 통과한 P-Val 을 다시 보지 않는다.
+    """
+    name = state_path.name
+    prefix = "plan-body-verification-"
+    if not name.startswith(prefix):
+        return
+    prepared = state_path.with_name("plan-items-" + name.removeprefix(prefix))
+    if not prepared.is_file():
+        return
+    queue = (
+        merged.get("planBodyVerification", {}).get("dispatchQueue")
+        if isinstance(merged.get("planBodyVerification"), Mapping)
+        else None
+    )
+    if not isinstance(queue, list):
+        return
+    try:
+        envelope = load_owned_object(prepared, artifact="prepared plan items")
+    except (OSError, ValueError):
+        return
+    if not isinstance(envelope, dict):
+        return
+    envelope["dispatchQueue"] = queue
+    write_json_atomic(prepared, envelope)
+
+
 def _parse_stage_csv(value: str | None, *, option: str) -> set[int] | None:
     if value is None:
         return None
@@ -457,6 +600,7 @@ def main(argv: list[str]) -> int:
 
     try:
         write_json_atomic(output, merged)
+        _sync_prepared_dispatch_queue(output, merged)
     except OSError as exc:
         print(f"carry refused: --out could not be written: {exc}", file=sys.stderr)
         return 1

package/runtime/python/okstra_ctl/incremental_scope.py

@@ -34,9 +34,8 @@ DECLARED_FULL_PREFIX = "declared structural change:"
 UNRESOLVED_MODE = "unresolved"
 
 # `P-Step-<stage>.<step>` and `P-Prep-S<stage>-<kind>` carry their stage in the
-# id itself. Every other prefix (`P-Opt`, `P-Dep`, `P-Val`, `P-Rb`, `P-Req`) is
-# numbered by position in its own array, so its stage is only recoverable from
-# the prose the planner wrote.
+# id itself. Every other prefix is numbered by position; its stage comes from
+# `stageScope` / `stageRefs`, then from the prose the planner wrote.
 _STRUCTURAL_STAGE_IN_ID_RE = re.compile(r"^P-(?:Step-(\d+)\.\d+|Prep-S(\d+)-)")
 
 
@@ -131,10 +130,32 @@ def design_prep_impacted_stages(data: dict, item_ids: set[str]) -> set[int]:
     return impacted
 
 
+def _int_stages(value: object) -> set[int]:
+    if not isinstance(value, list):
+        return set()
+    stages: set[int] = set()
+    for entry in value:
+        if isinstance(entry, int) and not isinstance(entry, bool) and entry >= 1:
+            stages.add(entry)
+    return stages
+
+
 def _plan_item_stages(item: dict) -> set[int]:
+    """항목이 걸린 스테이지. id 좌표, 그다음 기록된 범위, 그다음 산문.
+
+    `P-Val-*` / `P-Req-*` 는 위치 번호라 id 에서 스테이지가 안 나온다. 행이
+    `stageScope` / `stageRefs` 를 실어도 산문 `subject` 만 읽으면 C-039 같은
+    답이 unlinked 가 되어 재실행이 full 로 떨어진다.
+    """
     structural = _STRUCTURAL_STAGE_IN_ID_RE.match(str(item.get("id") or ""))
     if structural:
         return {int(structural.group(1) or structural.group(2))}
+    stages = _int_stages(item.get("stageScope")) or _int_stages(item.get("stageRefs"))
+    payload = item.get("payload")
+    if not stages and isinstance(payload, dict):
+        stages = _int_stages(payload.get("stageRefs"))
+    if stages:
+        return stages
     return cited_stage_numbers(str(item.get("subject") or ""))
 
 
@@ -169,6 +190,7 @@ def _stages_blocked_on(coverage: object, clarification_id: str) -> set[int]:
     for row in coverage if isinstance(coverage, list) else []:
         if coverage_row_blocked_on(row, clarification_id):
             stages |= cited_stage_numbers(str(row.get("coveredBy") or ""))
+            stages |= _int_stages(row.get("stageRefs"))
     return stages
 
 

package/runtime/python/okstra_ctl/plan_items.py

@@ -407,6 +407,15 @@ def expected_plan_item_ids(implementation_planning: Mapping[str, Any]) -> list[s
 
 _STARTABLE_STATUSES = frozenset({"ready", "active"})
 
+# 계획 전체를 판정하는 항목. 스테이지 하나를 고쳐도 요청하지 않은 작업이
+# 들어왔는지 다시 봐야 한다. P-Val / P-Req / P-Rb 는 여기 넣지 않는다 —
+# stageRefs 가 비어 있어도 이웃 수정의 일소 대상이 되면 C 행이 매 라운드 늘어난다.
+_PLAN_WIDE_ID_PREFIXES = ("P-Opt-", "P-Var-", "P-Dir-", "P-Dep-")
+
+
+def _is_plan_wide(item_id: str) -> bool:
+    return item_id.startswith(_PLAN_WIDE_ID_PREFIXES)
+
 
 def content_hash(item: Mapping[str, Any]) -> str:
     """이 항목 본문의 지문. 문구가 같으면 라운드가 달라도 같은 판정이다.
@@ -430,9 +439,13 @@ def stage_scope_bucket(
 ) -> str:
     """게이트·디스패치가 공유하는 범위. ``in-scope`` / ``observed`` / ``deferred``.
 
-    원장이 없거나 항목에 스테이지가 없으면 계획 전체로 읽는다. 검증기
+    원장이 없거나 계획 전체 항목이면 in-scope 이다. 검증기
     ``_stage_scope_bucket`` 과 같은 판정이어야 한다 — 디스패치와 게이트가
     다른 통을 쓰면 워커가 본 항목과 승인을 막는 항목이 갈라진다.
+
+    단계가 없는 ``P-Val`` / ``P-Req`` / ``P-Rb`` 는 원장에 ``done`` 이 생긴
+    뒤부터는 다음 착수를 막지 않는다. 생략된 ``stageRefs`` 를 모든 스테이지로
+    읽으면 이미 끝난 계획의 재실행마다 체크리스트 전부가 다시 채점된다.
     """
     if not isinstance(ledger, Mapping) or not ledger:
         return "in-scope"
@@ -442,6 +455,11 @@ def stage_scope_bucket(
         if isinstance(value, int) and not isinstance(value, bool)
     ] if isinstance(scope, list) else []
     if not stages:
+        item_id = str(item.get("id") or "")
+        if _is_plan_wide(item_id):
+            return "in-scope"
+        if "done" in {str(value) for value in ledger.values()}:
+            return "deferred"
         return "in-scope"
     statuses = {str(ledger.get(str(stage)) or "") for stage in stages}
     if statuses & _STARTABLE_STATUSES:
@@ -548,6 +566,10 @@ def reverify_item_ids(
 
     이전이 없으면 첫 라운드라 디스패치 큐 전부다. 해시가 같은 다른 스테이지
     항목은 보내지 않는다 — 그게 96개 일소 배치를 만들던 규칙이다.
+
+    단계가 없는 항목 전부가 계획 전체는 아니다. `P-Opt` / `P-Var` / `P-Dir` /
+    `P-Dep` 만 이웃 수정에 다시 묶인다. `P-Val` / `P-Req` / `P-Rb` 는 자기
+    해시가 바뀔 때만 다시 본다.
     """
     dispatched = dispatch_item_ids(items, ledger)
     by_id = {
@@ -558,8 +580,8 @@ def reverify_item_ids(
     if not previous_hashes:
         return dispatched
     changed = [
-        item_id for item_id in dispatched
-        if previous_hashes.get(item_id) != content_hash(by_id[item_id])
+        item_id for item_id, item in by_id.items()
+        if previous_hashes.get(item_id) != content_hash(item)
     ]
     changed_stages: set[int] = set()
     for item_id in changed:
@@ -570,6 +592,7 @@ def reverify_item_ids(
                 if isinstance(value, int) and not isinstance(value, bool)
             )
     queue: list[str] = []
+    queued: set[str] = set()
     for item_id in dispatched:
         item = by_id[item_id]
         scope = item.get("stageScope")
@@ -578,11 +601,24 @@ def reverify_item_ids(
             if isinstance(value, int) and not isinstance(value, bool)
         ] if isinstance(scope, list) else []
         if not stages:
-            if changed:
+            if item_id in changed or (changed and _is_plan_wide(item_id)):
                 queue.append(item_id)
+                queued.add(item_id)
             continue
         if item_id in changed or changed_stages.intersection(stages):
             queue.append(item_id)
+            queued.add(item_id)
+    # done 이후 디스패치에서 빠진 체크리스트라도 본문이 바뀌면 다시 본다.
+    for item_id in changed:
+        if item_id in queued or item_id not in by_id:
+            continue
+        scope = by_id[item_id].get("stageScope")
+        stages = [
+            value for value in scope
+            if isinstance(value, int) and not isinstance(value, bool)
+        ] if isinstance(scope, list) else []
+        if not stages:
+            queue.append(item_id)
     return queue
 
 

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

@@ -1,8 +1,6 @@
 """Common data transformations that carry no task-specific section order."""
 from __future__ import annotations
 
-import re
-
 
 # Every block whose rows prose cites but no section of its own renders, with
 # the keys each one names its content, its provenance, and its confidence by. A
@@ -97,14 +95,69 @@ def _own_section_ids(data: dict, omitted_fields: tuple[str, ...] = ()) -> set[st
     return found
 
 
-def evidence_index(data: dict) -> dict[str, object]:
+_OMITTED_TEXT_KEYS = (
+    "subject",
+    "check",
+    "item",
+    "action",
+    "requiredWork",
+    "statement",
+    "summary",
+    "need",
+    "title",
+)
+
+
+def _omitted_row_text(row: dict) -> str:
+    """생략된 행에서 독자가 읽을 한 줄을 고른다."""
+    for key in _OMITTED_TEXT_KEYS:
+        value = row.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return ""
+
+
+def _collect_row_dicts(value: object, rows: dict[str, dict]) -> None:
+    if isinstance(value, dict):
+        row_id = value.get("id") or value.get("activityId") or value.get("clarificationId")
+        if isinstance(row_id, str) and row_id:
+            rows.setdefault(row_id, value)
+        for nested in value.values():
+            _collect_row_dicts(nested, rows)
+    elif isinstance(value, list):
+        for nested in value:
+            _collect_row_dicts(nested, rows)
+
+
+def _omitted_rows(data: dict, omitted_fields: tuple[str, ...]) -> dict[str, dict]:
+    from ..report_contract import TASK_TYPE_DATA_PROPERTY
+
+    property_name = TASK_TYPE_DATA_PROPERTY.get(
+        (data.get("header") or {}).get("taskType", "")
+    )
+    block = data.get(property_name) if property_name else None
+    if not isinstance(block, dict):
+        return {}
+    rows: dict[str, dict] = {}
+    for field in omitted_fields:
+        _collect_row_dicts(block.get(field), rows)
+    return rows
+
+
+def evidence_index(
+    data: dict, omitted_fields: tuple[str, ...] = ()
+) -> dict[str, object]:
     """The rows the ledger carries, keyed by id.
 
     A row whose statement came out empty is dropped rather than listed: the
     ledger exists so a cited id resolves to something the reader can read, and
     an id above a blank line resolves to nothing.
+
+    `omitted_fields` are task-block arrays the HTML template does not render
+    as their own section. Their rows still have to land somewhere, because
+    prose cites them — without a ledger entry the id in the body is dead text.
     """
-    owned = _own_section_ids(data)
+    owned = _own_section_ids(data, omitted_fields)
     rows: dict[str, object] = {}
     for path, text_key, source_key, confidence_key, kind in _LEDGER_BLOCKS:
         for row in _dig(data, path):
@@ -116,12 +169,26 @@ def evidence_index(data: dict) -> dict[str, object]:
             entry = _ledger_row(row, text_key, source_key, confidence_key, kind)
             if entry["text"]:
                 rows[row_id] = entry
+    for row_id, row in _omitted_rows(data, omitted_fields).items():
+        if row_id in owned or row_id in rows:
+            continue
+        text = _omitted_row_text(row)
+        if not text:
+            continue
+        rows[row_id] = {
+            "id": row_id,
+            "kind": "plan-item",
+            "text": text,
+            "codeEvidence": [],
+            "source": "",
+            "confidence": "",
+        }
     return rows
 
 
 def _collect_ids(value: object, found: set[str]) -> None:
     if isinstance(value, dict):
-        for key in ("id", "activityId"):
+        for key in ("id", "activityId", "clarificationId"):
             row_id = value.get(key)
             if isinstance(row_id, str) and row_id:
                 found.add(row_id)
@@ -132,7 +199,9 @@ def _collect_ids(value: object, found: set[str]) -> None:
             _collect_ids(nested, found)
 
 
-_ROW_ID = re.compile(r"[A-Z]{1,3}-\d+")
+def _anchorable(row_id: str) -> bool:
+    """공백이나 경로 구분자가 있는 값은 HTML id 로 쓰지 않는다."""
+    return bool(row_id) and " " not in row_id and "/" not in row_id
 
 
 def anchor_index(data: dict, omitted_fields: tuple[str, ...] = ()) -> dict[str, str]:
@@ -141,15 +210,21 @@ def anchor_index(data: dict, omitted_fields: tuple[str, ...] = ()) -> dict[str,
     Prose cites ids across section boundaries — a hotspot names a
     cross-verification finding, a quality row names a difference — so the
     target set spans the whole reader-facing report: the task's own sections,
-    the clarifications, and every block the ledger takes in.
+    the clarifications, and every block the ledger takes in, including rows
+    whose section the template left out.
 
     It stops there. `summary` is the AI-facing digest and
     `analysisCommon.scope` describes the analysis target rather than listing
-    rows; neither renders, so a link to one would land nowhere. Same for the
-    blocks a template declares in `omitted_fields`.
+    rows; neither renders, so a link to one would land nowhere.
     """
-    found = _own_section_ids(data, omitted_fields) | set(evidence_index(data))
-    return {row_id: f"id-{row_id}" for row_id in sorted(found) if _ROW_ID.fullmatch(row_id)}
+    found = _own_section_ids(data, omitted_fields) | set(
+        evidence_index(data, omitted_fields)
+    )
+    return {
+        row_id: f"id-{row_id}"
+        for row_id in sorted(found)
+        if isinstance(row_id, str) and _anchorable(row_id)
+    }
 
 
 def analysis_review_ids(data: dict) -> tuple[str, ...]:

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

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import re
+from functools import lru_cache
 
 import okstra_vendor  # noqa: F401  # registers vendored dependency aliases
 from markupsafe import Markup, escape
@@ -9,12 +10,24 @@ from markupsafe import Markup, escape
 _INLINE_CODE = re.compile(r"`([^`]+)`")
 _SENTENCE_END = re.compile(r"(?<=[.!?])\s+")
 _SENTENCES_PER_PARAGRAPH = 2
-# `\b` after the digits would end the token only where the next character is
-# non-word, and a Korean particle is a word character — `EA-001에` matched
-# nothing, so every id a translated report cites mid-sentence lost its link
-# while the English source kept it. The boundary a row id actually needs is
-# "not part of a longer alphanumeric run", which is what these assertions say.
-_ID_TOKEN = re.compile(r"(?<![A-Za-z0-9])[A-Z]{1,3}-\d+(?!\d)")
+
+
+@lru_cache(maxsize=16)
+def _anchors_pattern(keys: tuple[str, ...]) -> re.Pattern[str] | None:
+    """이 문서가 실제로 가진 아이디만, 긴 것부터 맞춘다.
+
+    고정 `[A-Z]{1,3}-\\d+` 토큰은 `PREP-001` 과 `P-Step-5.1` 을 놓쳐
+    행이 페이지에 있어도 본문이 그냥 글자가 됐다. 인덱스에 있는 키로
+    패턴을 만들면 `DEV-10339` 같은 티켓은 그 id 의 행이 없을 때 링크되지 않는다.
+    """
+    if not keys:
+        return None
+    ordered = tuple(sorted(keys, key=len, reverse=True))
+    return re.compile(
+        r"(?<![A-Za-z0-9])(?:"
+        + "|".join(re.escape(key) for key in ordered)
+        + r")(?![A-Za-z0-9])"
+    )
 
 
 def _link_ids(escaped: str, anchors: dict) -> str:
@@ -27,12 +40,16 @@ def _link_ids(escaped: str, anchors: dict) -> str:
     """
     if not anchors:
         return escaped
+    pattern = _anchors_pattern(tuple(sorted(anchors)))
+    if pattern is None:
+        return escaped
 
-    def swap(match: re.Match) -> str:
-        name = anchors.get(match.group(0))
-        return f'<a href="#{name}">{match.group(0)}</a>' if name else match.group(0)
+    def swap(match: re.Match[str]) -> str:
+        token = match.group(0)
+        name = anchors.get(token)
+        return f'<a href="#{name}">{token}</a>' if name else token
 
-    return _ID_TOKEN.sub(swap, escaped)
+    return pattern.sub(swap, escaped)
 
 
 def inline_code(value: object, anchors: dict | None = None) -> Markup:

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

@@ -153,6 +153,7 @@ def render_v2_html_view(
         "runMeta": run_meta,
         "reportMeta": _report_meta(data, run_meta),
         "taskType": view.task_type,
+        "lang": lang,
         "sourceData": source_data,
         "dataSha256": _sha256(data_path),
         "clarificationItems": data.get("clarificationItems", []),

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

@@ -24,6 +24,8 @@ _SLUG_RE = re.compile(r'\bdata-report-section="([^"]+)"')
 _TAG_RE = re.compile(r"<[^>]+>")
 
 INDEX_TITLE_ID = "report-index-title"
+# 맨 위로 버튼 패널에 같은 목차 항목을 채우는 자리. 본문 목차와 한 함수에서 만든다.
+_INDEX_ITEMS_SLOT = "<!--report-index-items-->"
 
 
 def _heading_text(title_markup: str) -> str:
@@ -34,6 +36,7 @@ def _heading_text(title_markup: str) -> str:
 def inject_report_index(document: str, *, label: str) -> str:
     """Return ``document`` with a section index at the top of ``<main>``.
 
+    The same list fills the back-to-top hover panel, so the two cannot drift.
     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.
@@ -72,4 +75,5 @@ def inject_report_index(document: str, *, label: str) -> str:
         f"<ol>{items}</ol>"
         "</nav>"
     )
-    return f"{head}\n{index}{body}"
+    filled = f"{head}\n{index}{body}"
+    return filled.replace(_INDEX_ITEMS_SLOT, f"<ol>{items}</ol>", 1)

package/runtime/python/okstra_ctl/report_html/view_models/implementation_planning.py

@@ -134,7 +134,7 @@ def build_implementation_planning_view(data: dict) -> HumanReportView:
             row["activityId"]: row for row in activities if row.get("activityId")
         },
         "decisionCards": decision_cards,
-        "evidenceIndex": evidence_index(data),
+        "evidenceIndex": evidence_index(data, _OMITTED_FIELDS),
     }
     return HumanReportView(
         "implementation-planning",

package/runtime/skills/okstra-chat/SKILL.md

@@ -59,26 +59,46 @@ If the host has a native picker, use it. Otherwise print a numbered list.
 okstra chat unread --room <room> --as <display>
 ```
 
-Show the rows. Each row is `id:time:recipient:body`.
+Show the rows. Each row is `id @from YYYY-MM-DD HH:MM body`. Sender is always `@name`. The id is the first token (before the first space). A reply inserts `↑<parentId>` after the time. Recipient is not on the line.
+
+If the output is `no unread`, do not ack.
+
+If there are unread rows, always run:
+
+```bash
+okstra chat ack --room <room> --as <display> --through <id>
+```
+
+Use the last unread row's id. CLI unread does not move the cursor; this ack does.
 
 ## Step 3: Next action
 
-Ask: send, inbox, log, ack, or done.
+Ask: send, unread, inbox, log, reply, or done.
+
+There is no ack menu item. Choosing unread again shows the rows then acks, same as Step 2.
 
 ### Send
 
 1. Run `okstra chat members --room <room>`.
-2. Pick the recipient from `all` plus those names. Recipient is required.
+2. Pick the recipient from `all` plus those names except the current display name (`--as`). Filter after `okstra chat members`. Do not pass `--as` to `members`. Recipient is required.
 3. Ask for the body as free input.
 4. Run `okstra chat send --room <room> --as <display> --to <all|name> --body <text>`.
 
+### Reply
+
+1. Ask for the parent message id as free input.
+2. Ask for the body as free input.
+3. Run `okstra chat send --room <room> --as <display> --reply-to <id> --body <text>`.
+
+Do not pick a recipient. There is no reply subcommand.
+
 ### Inbox
 
 ```bash
 okstra chat inbox --room <room> --as <display>
 ```
 
-This is every arrival to `@you` or `all`, including messages already acked.
+This is every arrival to `@you` or `all`, including messages already acked and messages you sent to `all` or to yourself. Inbox does not move the cursor.
 
 ### Log
 
@@ -86,15 +106,7 @@ This is every arrival to `@you` or `all`, including messages already acked.
 okstra chat log --room <room> --as <display>
 ```
 
-The whole room, including messages not addressed to you.
-
-### Ack
-
-After unread, mark the last id the user has read:
-
-```bash
-okstra chat ack --room <room> --as <display> --through <id>
-```
+The whole room, including messages not addressed to you. Log does not move the cursor.
 
 ## Rules