okstra 0.54.0 → 0.55.0

package/package.json

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

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.54.0",
-  "builtAt": "2026-06-06T15:10:15.217Z",
+  "package": "0.55.0",
+  "builtAt": "2026-06-06T16:37:32.221Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/report-writer-worker.md

@@ -101,7 +101,7 @@ Rules (the schema enforces most of these — they are listed here so you know *w
 - Cite file paths and line numbers in every `evidence.primary[].source` / `consensus[].evidence` cell.
 - Preserve every analysis worker's ticket tagging — every row's `ticketId` field carries the ticket key or the task-fallback. For single-ticket runs, set `ticketCoverage` to `{"singleTicket": "<ticket>"}`. For runs that do not require ticket tagging (`release-handoff`, `final-verification`), set `ticketCoverage` to `{"omit": true}`.
 - For `implementation-planning`, populate `implementationPlanning.requirementCoverage` with one row per concrete requirement from the brief / packet, using IDs `R-001`, `R-002`, ... in source order. `coveredBy` MUST name the specific Option Candidate plus Stage/Step that satisfies the requirement. Use `status: "covered"` only when the report's plan actually covers it; otherwise use `gap` or `blocked C-NNN` and ensure the corresponding `Clarification Items` row blocks approval. Do not collapse this into `ticketCoverage`; ticket coverage is not requirement coverage.
-- When the `Task Type` is `improvement-discovery`, populate `## 5.9 Improvement Candidates` with the 10-column schema enforced by `validators/validate-improvement-report.py`. Source the row IDs (`I-NNN`), lens whitelist, and Source workers patterns from `scripts/okstra_ctl/improvement_lenses.py` — do NOT introduce new lens names or worker prefixes.
+- When the `Task Type` is `improvement-discovery`, populate `## 5.9 Improvement Candidates` with the 10-column schema enforced by `validators/validate-improvement-report.py`. Source the row IDs (`I-NNN`), lens whitelist, and Source workers patterns from `scripts/okstra_ctl/improvement_lenses.py` — do NOT introduce new lens names or worker prefixes. `improvement-discovery` is NOT in the data.json schema enum, so author its markdown directly (not via `okstra-render-final-report.py`). Immediately after writing the markdown, run (`Bash`): `python3 scripts/okstra-inject-report-index.py <markdown path> --report-language <en|ko>`. That adds the top-of-report Index plus `I-NNN` / `C-NNN` scroll anchors; the run validator fails the report when the Index anchor is absent.
 
 Write the data.json with your `Write` tool against the absolute `Result Path`. Then invoke the renderer (`Bash`): `python3 scripts/okstra-render-final-report.py <data.json path>`. Confirm both files exist and respond with a short status line: `data.json written to <abs path>; markdown rendered to <abs path>. Sections populated: <count>.`
 

package/runtime/bin/okstra-inject-report-index.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""CLI entry for the top-of-report index / scroll-anchor injector.
+
+Usage:
+    python3 scripts/okstra-inject-report-index.py \\
+        <final-report.md> \\
+        [--report-language en|ko]
+
+Adds the top-of-report Index (section list + ID index) and `<a id="...">`
+scroll anchors to a markdown report that was authored *free-form* rather
+than rendered from a data.json. The only such task-type today is
+`improvement-discovery`: its `## 5.9 Improvement Candidates` table is
+written directly by the report-writer worker, so the data.json renderer
+(which injects the index for every other task-type) never sees it.
+
+Idempotent — re-running on an already-indexed report is a no-op.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+# Make ``okstra_ctl`` importable for in-repo invocation (the installed
+# runtime adds ``~/.okstra/lib/python`` via the wrapper scripts).
+sys.path.insert(0, str(_HERE))
+
+from okstra_ctl.i18n import SUPPORTED_LANGS  # noqa: E402
+from okstra_ctl.render_final_report import (  # noqa: E402
+    FinalReportRenderError,
+    inject_index_into_file,
+)
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description="Inject the top-of-report index + scroll anchors into a free-form markdown report.",
+    )
+    parser.add_argument(
+        "report",
+        type=Path,
+        help="Path to the final-report markdown to rewrite in place.",
+    )
+    parser.add_argument(
+        "--report-language",
+        choices=list(SUPPORTED_LANGS),
+        default="en",
+        help="Language for the index labels (Index/목차, …). Default: en.",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        bytes_written = inject_index_into_file(
+            args.report, report_language=args.report_language
+        )
+    except FinalReportRenderError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"injected index + anchors -> {args.report} ({bytes_written} bytes)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/prompts/profiles/improvement-discovery.md

@@ -32,6 +32,7 @@
   - the `## 5.9 Improvement Candidates` table populated with rows that obey the 10-column schema from `validators/validate-improvement-report.py` (Cand ID `I-NNN`, Lens from whitelist, Title, Scope ⊆ scan-scope, Severity, Effort, Consensus, Source workers `<worker>:<id>` from {claude, codex, gemini}, Recommended next-phase ∈ {requirements-discovery, implementation-planning, error-analysis}, Evidence as path:line list)
   - `## 7. Final Verdict` Verdict Token ∈ {`candidates-ready`, `no-candidates`, `blocked`}; Direction `routing`; Next Step "사용자에게 후보 K개 선택 의뢰 (## 5.9 표 참조)"
   - `## 3. Recommended Next Steps` first entry summarises per-candidate routing and proposes new task-key names of the form `<task-group>/imp-<Cand-ID>`
+  - this report is authored free-form (improvement-discovery is not in the data.json schema enum); after the markdown is written, the report-writer runs `scripts/okstra-inject-report-index.py <report.md> --report-language <en|ko>` to add the top-of-report Index + `I-NNN`/`C-NNN` scroll anchors. The run validator fails the report when the Index anchor is missing.
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
   - if scan-scope or priority-lenses cannot be made concrete during Phase 1.5, end the run with Verdict Token `blocked`, populate `## 1. Clarification Items` with `Blocks=next-phase` rows, and do not run worker dispatch
   - every clarification row carries a recommended answer + one-line rationale inside the `Expected form` cell

package/runtime/python/okstra_ctl/clarification_items.py

@@ -46,8 +46,17 @@ class ClarificationItem:
     raw_status: str
 
 
+# The final-report renderer injects a scroll anchor into ID-defining first
+# cells — either leading (`<a id="c-001"></a>C-001`) or inside the bold marker
+# (`**<a id="e-001"></a>E-001**`). Strip every such empty anchor during cell
+# normalization so the ID parses as a bare token for clarification parsing AND
+# the HTML view's `C-\d+` form detection, and so the anchor never leaks into
+# the HTML view as html-escaped literal text.
+_CELL_ANCHOR_RE = re.compile(r'<a id="[^"]*"></a>')
+
+
 def _strip_backticks(cell: str) -> str:
-    s = cell.strip()
+    s = _CELL_ANCHOR_RE.sub("", cell.strip()).strip()
     if s.startswith("`") and s.endswith("`") and len(s) >= 2:
         s = s[1:-1].strip()
     return s

package/runtime/python/okstra_ctl/render_final_report.py

@@ -10,9 +10,17 @@ the canonical user-facing markdown.
 Why this exists: prior to v0.32, report-writer-worker wrote the markdown
 directly. Free-form authoring led to silent contract violations — missing
 columns in the Execution Status table, omitted §4 phase-continuation
-rows, invented ``## Index`` sections. Routing everything through one
+rows, ad-hoc ``## Index`` sections. Routing everything through one
 template + schema cuts those failure modes to zero.
 
+The top-of-report ``## Index`` is now a *deterministic* post-render
+section: after Jinja2 renders the body, ``_inject_index_and_anchors``
+appends a scroll anchor to every heading and every ID-defining table row,
+links in-body ID references to their definition, and builds the index
+(section list + ID index) — so every ``FU-001`` / ``E-001`` / ``S-001``
+token is clickable and the reader can jump to any section. This runs on
+every render (including the Phase 7 re-render) and is idempotent.
+
 Phase 7 mutation flow: ``okstra-token-usage.py --substitute-data`` fills
 the ``tokenUsage`` and ``executionStatus[].totalTokens`` etc. cells in
 data.json, then re-invokes this renderer so the markdown stays in sync.
@@ -27,6 +35,7 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import sys
 from pathlib import Path
 from typing import Any
@@ -110,6 +119,215 @@ def _yaml_inline_list(values: list[str]) -> str:
     return "[" + ", ".join(_yaml_scalar(v) for v in values) + "]"
 
 
+# --- Index / scroll-anchor post-render pass -------------------------------
+# After Jinja2 renders the body, every report gets a top-of-report index and
+# clickable scroll anchors. An ID is *defined* when it is the leading token of
+# a table row's first cell (`| **FU-001**<br>… |` or `| C-001 | …`); that row
+# gets an `<a id="…">` anchor. Every other in-body mention of a *uniquely*
+# defined ID becomes a `[ID](#anchor)` link. Same ID string defined in two
+# sections (e.g. `C-001` in §1 Clarification AND §6.1 Consensus) gets two
+# distinct anchors and its bare references are left unlinked — an ambiguous
+# reference must not silently jump to the wrong row.
+_HEADING_RE = re.compile(r"^(#{1,6})[ \t]+(.*?)[ \t]*$")
+_FENCE_RE = re.compile(r"^[ \t]*(?:```|~~~)")
+_FIRST_CELL_ID_RE = re.compile(r"^[ \t]*\*{0,2}([A-Z]{1,4}-\d{3,})\b")
+# A reference token: an ID not glued to a word char / `-` on either side and
+# not prefixed by `:` (which would make it a `<worker>:<item-id>` source ref).
+_REF_ID_RE = re.compile(r"(?<![:\w-])[A-Z]{1,4}-\d{3,}(?![\w-])")
+
+
+def _slugify(text: str) -> str:
+    slug = re.sub(r"[^\w\s-]", "", text.strip().lower())
+    slug = re.sub(r"[\s_]+", "-", slug).strip("-")
+    return slug or "section"
+
+
+def _dedupe(base: str, used: set[str]) -> str:
+    candidate, suffix = base, 1
+    while candidate in used:
+        suffix += 1
+        candidate = f"{base}-{suffix}"
+    used.add(candidate)
+    return candidate
+
+
+def _code_line_mask(lines: list[str]) -> list[bool]:
+    """Mark lines the anchor / reference passes must never rewrite: fenced
+    code blocks (git status dumps, etc.) and the leading YAML frontmatter
+    (a `task-id` that happens to look like an ID must not be linkified)."""
+    frontmatter_end = -1
+    if lines and lines[0].strip() == "---":
+        for k in range(1, len(lines)):
+            if lines[k].strip() == "---":
+                frontmatter_end = k
+                break
+    mask, in_fence = [], False
+    for i, line in enumerate(lines):
+        if i <= frontmatter_end:
+            mask.append(True)
+        elif _FENCE_RE.match(line):
+            mask.append(True)
+            in_fence = not in_fence
+        else:
+            mask.append(in_fence)
+    return mask
+
+
+def _first_cell(line: str) -> str | None:
+    if not line.lstrip().startswith("|"):
+        return None
+    parts = line.split("|")
+    return parts[1] if len(parts) >= 3 else None
+
+
+def _scan_structure(lines: list[str], mask: list[bool]) -> tuple[list, list]:
+    """Collect (level, text, slug, line_idx) headings and {id, section,
+    line} definitions in document order. H1 (the title) is skipped."""
+    headings: list = []
+    definitions: list = []
+    used_slugs: set[str] = set()
+    current_section: str | None = None
+    for i, line in enumerate(lines):
+        if mask[i]:
+            continue
+        heading = _HEADING_RE.match(line)
+        if heading:
+            if len(heading.group(1)) < 2:
+                continue  # H1 title — not an index entry, no anchor
+            text = heading.group(2).strip()
+            slug = _dedupe(_slugify(text), used_slugs)
+            headings.append((len(heading.group(1)), text, slug, i))
+            current_section = text
+            continue
+        cell = _first_cell(line)
+        if cell is None:
+            continue
+        match = _FIRST_CELL_ID_RE.match(cell)
+        if match:
+            definitions.append({"id": match.group(1), "section": current_section, "line": i})
+    return headings, definitions
+
+
+def _assign_anchors(definitions: list) -> dict[str, str]:
+    """Give every definition a unique anchor; return the id→anchor map for
+    the subset of IDs that are defined exactly once (safe to link)."""
+    used: set[str] = set()
+    counts: dict[str, int] = {}
+    for d in definitions:
+        counts[d["id"]] = counts.get(d["id"], 0) + 1
+    for d in definitions:
+        d["anchor"] = _dedupe(d["id"].lower(), used)
+    return {d["id"]: d["anchor"] for d in definitions if counts[d["id"]] == 1}
+
+
+def _inject_anchors(lines: list[str], headings: list, definitions: list) -> None:
+    for _level, _text, slug, i in headings:
+        if "<a id=" not in lines[i]:
+            lines[i] = lines[i].rstrip() + f' <a id="{slug}"></a>'
+    for d in definitions:
+        i = d["line"]
+        pos = lines[i].index(d["id"])
+        lines[i] = lines[i][:pos] + f'<a id="{d["anchor"]}"></a>' + lines[i][pos:]
+
+
+def _maybe_link(match: re.Match, id_to_anchor: dict[str, str]) -> str:
+    token = match.group(0)
+    anchor = id_to_anchor.get(token)
+    if anchor is None:
+        return token
+    # The definition site is already `<a id="…"></a>**FU-001**`; never wrap it.
+    if match.string[: match.start()].rstrip("*").endswith("</a>"):
+        return token
+    return f"[{token}](#{anchor})"
+
+
+def _link_references(lines: list[str], mask: list[bool], id_to_anchor: dict[str, str]) -> None:
+    if not id_to_anchor:
+        return
+    for i, line in enumerate(lines):
+        if mask[i]:
+            continue
+        # Split on backticks so inline-code spans (odd segments) are skipped.
+        segments = line.split("`")
+        for j in range(0, len(segments), 2):
+            segments[j] = _REF_ID_RE.sub(lambda m: _maybe_link(m, id_to_anchor), segments[j])
+        lines[i] = "`".join(segments)
+
+
+def _build_index(headings: list, definitions: list, labels: dict) -> list[str]:
+    # The section list / ID index use bold labels, not `###` sub-headings, so
+    # the HTML view's auto-TOC (report_views._build_toc) doesn't pick them up
+    # as navigable headings.
+    heading = labels.get("heading", "Index")
+    block = [f'## {heading} <a id="report-index"></a>', "", f'**{labels.get("sectionsLabel", "Sections")}**', ""]
+    for level, text, slug, _i in headings:
+        block.append(f'{"  " * (level - 2)}- [{text}](#{slug})')
+    block += ["", f'**{labels.get("idIndexLabel", "ID Index")}**', ""]
+    if not definitions:
+        block += [labels.get("noIds", "- (no tracked IDs in this report.)"), ""]
+        return block
+    groups: list = []
+    order: dict = {}
+    for d in definitions:
+        section = d["section"] or "—"
+        if section not in order:
+            order[section] = len(groups)
+            groups.append((section, []))
+        groups[order[section]][1].append((d["id"], d["anchor"]))
+    for section, items in groups:
+        links = ", ".join(f"[{tok}](#{anchor})" for tok, anchor in items)
+        block.append(f"- **{section}**: {links}")
+    block.append("")
+    return block
+
+
+def _inject_index_and_anchors(markdown: str, dictionary: dict | None) -> str:
+    """Append scroll anchors + a top-of-report index to a rendered report.
+    Idempotent: re-running on already-anchored markdown is a no-op for
+    headings (anchor already present) and re-derives the same anchors."""
+    # Idempotent: a markdown that already carries the index anchor has been
+    # processed (or hand-seeded) — re-running must not stack a second index.
+    if '<a id="report-index"' in markdown:
+        return markdown
+    labels = (dictionary or {}).get("index", {})
+    lines = markdown.split("\n")
+    mask = _code_line_mask(lines)
+    headings, definitions = _scan_structure(lines, mask)
+    if not headings:
+        return markdown
+    id_to_anchor = _assign_anchors(definitions)
+    _inject_anchors(lines, headings, definitions)
+    _link_references(lines, mask, id_to_anchor)
+    insert_at = headings[0][3]
+    lines = lines[:insert_at] + _build_index(headings, definitions, labels) + lines[insert_at:]
+    return "\n".join(lines)
+
+
+def inject_index_into_file(md_path: Path, *, report_language: str = "en") -> int:
+    """Apply the top-of-report index + scroll anchors to an already-written
+    markdown report, in place. This is the seam for task-types that author
+    the markdown free-form (``improvement-discovery``) instead of through the
+    data.json renderer — every other task-type gets the same treatment inside
+    ``render()``. Idempotent (the index anchor guards re-runs). Returns the
+    number of bytes written.
+    """
+    if not md_path.is_file():
+        raise FinalReportRenderError(f"report markdown not found: {md_path}")
+    if report_language not in SUPPORTED_LANGS:
+        raise FinalReportRenderError(
+            f"report_language must be one of {SUPPORTED_LANGS}, got {report_language!r}"
+        )
+    try:
+        dictionary = load_dictionary(report_language)
+    except I18nError as exc:
+        raise FinalReportRenderError(str(exc)) from exc
+    injected = _inject_index_and_anchors(md_path.read_text(encoding="utf-8"), dictionary)
+    tmp = md_path.with_suffix(md_path.suffix + f".tmp.{os.getpid()}")
+    tmp.write_text(injected, encoding="utf-8")
+    tmp.replace(md_path)
+    return len(injected.encode("utf-8"))
+
+
 def _enforce_schema(data: dict) -> None:
     """렌더 전에 data.json 을 스키마에 대해 검증하는 seam.
 
@@ -203,7 +421,8 @@ def render(
 
     try:
         template = env.get_template(template_path.name)
-        return template.render(**data)
+        rendered = template.render(**data)
+        return _inject_index_and_anchors(rendered, dictionary)
     except I18nError as exc:
         raise FinalReportRenderError(
             f"i18n lookup failed while rendering {template_path.name}: {exc}"

package/runtime/python/okstra_ctl/report_views.py

@@ -169,8 +169,12 @@ def _markdown_to_html(
         m_heading = _HEADING_PATTERN.match(line)
         if m_heading:
             level = len(m_heading.group(1))
-            text = m_heading.group(2)
-            slug = _slugify(text)
+            # The final-report renderer appends an explicit scroll anchor to
+            # each heading (`## Verdict Card <a id="verdict-card"></a>`). Honor
+            # that id as the slug (keeps markdown ↔ HTML anchors consistent and
+            # language-independent) and drop it from the displayed text.
+            explicit_id, text = _split_heading_anchor(m_heading.group(2))
+            slug = explicit_id or _slugify(text)
             current_section_path = _update_section_path(current_section_path, level, line)
             out.append(f'<h{level} id="{slug}">{_inline(text)}</h{level}>')
             headings.append((level, slug, text))
@@ -235,11 +239,26 @@ def _markdown_to_html(
     return "\n".join(out), headings
 
 
+_HEADING_ANCHOR_RE = re.compile(r'\s*<a id="([^"]+)"></a>\s*$')
+
+# The renderer's top-of-report Index section (`## Index`/`## 목차` carrying
+# `<a id="report-index">`, followed by bold-labelled bullet lists). The whole
+# section — heading through the bullet lists, up to the next h2 — is replaced
+# by the auto-built nav.
 _INDEX_BLOCK_RE = re.compile(
-    r'<h2 id="index">Index</h2>\n<ul>.*?</ul>', re.DOTALL
+    r'<h2 id="report-index">.*?(?=<h2|\Z)', re.DOTALL
 )
 
 
+def _split_heading_anchor(text: str) -> tuple[Optional[str], str]:
+    """Split a trailing ``<a id="…"></a>`` off a heading's text. Returns
+    ``(explicit_id_or_None, display_text)``."""
+    match = _HEADING_ANCHOR_RE.search(text)
+    if match:
+        return match.group(1), text[: match.start()].rstrip()
+    return None, text
+
+
 def _build_toc(headings: list[tuple[int, str, str]]) -> str:
     """Render a ``<nav class="toc">`` block from collected h2/h3 entries.
     h1 (the report title) is omitted; h4+ are too granular for the TOC."""
@@ -247,7 +266,7 @@ def _build_toc(headings: list[tuple[int, str, str]]) -> str:
     for level, slug, text in headings:
         if level not in (2, 3):
             continue
-        if slug == "index":  # skip the source "Index" heading itself
+        if slug == "report-index":  # skip the source Index/목차 heading itself
             continue
         cls = "toc-h2" if level == 2 else "toc-h3"
         items.append(

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

@@ -137,5 +137,11 @@
     "columnRequirement": "Requirement (plan/brief citation)",
     "verificationScope": "Verification scope",
     "stageReportsLabel": "Source implementation reports (per stage)"
+  },
+  "index": {
+    "heading": "Index",
+    "sectionsLabel": "Sections",
+    "idIndexLabel": "ID Index",
+    "noIds": "- (no tracked IDs in this report.)"
   }
 }

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

@@ -137,5 +137,11 @@
     "columnRequirement": "Requirement (plan/brief 인용)",
     "verificationScope": "검증 범위",
     "stageReportsLabel": "stage 별 구현 리포트"
+  },
+  "index": {
+    "heading": "목차",
+    "sectionsLabel": "섹션",
+    "idIndexLabel": "ID 색인",
+    "noIds": "- (이 보고서에 추적 대상 ID 가 없습니다.)"
   }
 }

package/runtime/validators/lib/fixtures.sh

@@ -323,6 +323,15 @@ if not isinstance(required_status_entries, list):
 report_lines = [
     "# Validation Fixture Report",
     "",
+    # Top-of-report Index — the renderer injects this on real runs; the
+    # hand-crafted fixture mirrors it so validate_report's index/anchor
+    # contract (introduced with the clickable-ID pass) is satisfied.
+    '## Index <a id="report-index"></a>',
+    "",
+    "### Sections",
+    "",
+    "- [Verdict Card](#verdict-card)",
+    "",
     "## Verdict Card",
     "",
     "| 항목 | 값 |",

package/runtime/validators/validate-run.py

@@ -616,6 +616,19 @@ def _scan_token_usage_summary(content: str, failures: list[str]) -> None:
 # a section heading line (not as inline text inside a paragraph or table).
 _VERDICT_CARD_HEADING_RE = re.compile(r"^##[ \t]+Verdict Card\b", re.MULTILINE)
 
+# Top-of-report Index block. The renderer
+# (scripts/okstra_ctl/render_final_report.py) injects `<a id="report-index">`
+# into the index heading; a missing anchor means the markdown was produced
+# outside the renderer or hand-edited. Language-independent (the heading text
+# itself is localized "Index" / "목차").
+_REPORT_INDEX_ANCHOR_RE = re.compile(r'<a id="report-index"')
+
+# An ID-defining table row: `| **FU-001**…` or `| C-001 |`. After the
+# renderer's anchor pass the leading token becomes `<a id="…">…`, so a row
+# still matching this (ID is the bare leading token) is one the renderer
+# never anchored — i.e. an un-anchored ID that the Index cannot link to.
+_UNANCHORED_ID_ROW_RE = re.compile(r"^\|[ \t]*\*{0,2}([A-Z]{1,4}-\d{3,})\b", re.MULTILINE)
+
 # Reading Confirmation heading must NOT appear in the final-report — it
 # belongs in the worker audit sidecar (`<worker>-audit-<task-type>-<seq>.md`).
 _READING_CONFIRMATION_HEADING_RE = re.compile(
@@ -723,6 +736,32 @@ def validate_report(
             "the corresponding cells in `## 7. Final Verdict` and `## 3.` first item."
         )
 
+    # Top-of-report Index (목차 / Index) is mandatory in every final-report so
+    # the reader can jump to any section / tracked ID. Schema task-types get it
+    # from render_final_report.py; `improvement-discovery` (authored free-form)
+    # gets it from the `okstra-inject-report-index.py` post-step. A missing
+    # index anchor means that injection never ran.
+    if _REPORT_INDEX_ANCHOR_RE.search(content) is None:
+        failures.append(
+            "final report is missing the top-of-report Index block "
+            '(`## Index` / `## 목차` carrying `<a id="report-index">`). It is '
+            "injected by scripts/okstra_ctl/render_final_report.py (schema "
+            "task-types) or scripts/okstra-inject-report-index.py "
+            "(improvement-discovery); a missing index means that step never ran."
+        )
+
+    # Every ID-defining table row (FU-/E-/S-/C-/R-/I-/… in the first cell) must
+    # carry a scroll anchor so the Index can link to it. A row still matching
+    # the bare-leading-token shape is one the injector never anchored.
+    for match in _UNANCHORED_ID_ROW_RE.finditer(content):
+        failures.append(
+            f"final report has an ID-defining table row for `{match.group(1)}` "
+            'without a scroll anchor (`<a id="…">`). IDs must be anchored so the '
+            "top-of-report Index can link to them — run the index injector "
+            "(render_final_report.py / okstra-inject-report-index.py) instead of "
+            "hand-editing."
+        )
+
     # Reading Confirmation belongs in the worker audit sidecar, not the
     # user-facing final-report.
     if _READING_CONFIRMATION_HEADING_RE.search(content) is not None:
@@ -1870,11 +1909,11 @@ def main() -> int:
     # data.json is well-formed, the rendered markdown is guaranteed to
     # contain every required section. Substring checks below are a
     # safety net for hand-edited or pre-v1.0 reports.
+    task_type = effective_run_task_type(run_manifest, task_manifest)
     validate_final_report_data(report_path, failures)
     validate_report(report_path, contract["required_agent_status_entries"], failures)
     validate_team_state_usage(team_state, failures)
 
-    task_type = effective_run_task_type(run_manifest, task_manifest)
     validate_phase_boundary(task_type, report_path, failures)
     if task_type:
         validate_worker_results_audit(report_path, task_type, failures)

package/runtime/validators/validate_improvement_report.py

@@ -30,6 +30,10 @@ _NEXT_PHASES = ("requirements-discovery", "implementation-planning", "error-anal
 _CAND_ID_RE = re.compile(r"^I-\d{3}$")
 _SOURCE_WORKER_RE = re.compile(r"^([a-z-]+):([A-Za-z0-9._-]+)$")
 _CONSENSUS_VALUES = ("full", "partial", "contested", "worker-unique")
+# The index/anchor post-pass (okstra-inject-report-index.py) injects an empty
+# scroll anchor into ID-defining first cells (`<a id="i-001"></a>I-001`). Strip
+# it during cell normalization so `_CAND_ID_RE` still matches the bare `I-NNN`.
+_CELL_ANCHOR_RE = re.compile(r'<a id="[^"]*"></a>')
 
 
 @dataclass
@@ -53,7 +57,7 @@ def _read_section_table(body: str, heading: str) -> list[list[str]]:
         s = line.strip()
         if not s.startswith("|") or not s.endswith("|"):
             continue
-        cells = [c.strip() for c in s.strip("|").split("|")]
+        cells = [_CELL_ANCHOR_RE.sub("", c).strip() for c in s.strip("|").split("|")]
         if all(set(c) <= set("-: ") for c in cells):
             continue
         rows.append(cells)