okstra 0.131.0 → 0.132.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.131.0",
+  "version": "0.132.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.131.0",
-  "builtAt": "2026-07-22T04:41:31.388Z",
+  "package": "0.132.0",
+  "builtAt": "2026-07-22T06:44:24.538Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/render_final_report.py

@@ -308,6 +308,66 @@ def _build_index(headings: list, definitions: list, labels: dict) -> list[str]:
     return block
 
 
+# --- Prose ventilation post-render pass -----------------------------------
+# Split prose paragraphs at sentence boundaries so raw markdown reads one
+# sentence per line; the HTML view turns those newlines into <br>
+# (report_views._markdown_to_html). Prose only — table cells already carry
+# their own <br>, and headings / lists / code / blockquotes must stay intact.
+# A leading-whitespace line is a list continuation, not a prose paragraph:
+# only column-0 non-block lines are treated as prose (allowlist).
+_LIST_LINE_RE = re.compile(r"^\s*(?:[-*]\s|\d+\.\s)")
+_SENT_BOUNDARY_RE = re.compile(r"[.?!][ \t]+(?=\S)")
+# Trailing tokens whose dot is not a sentence end (compared lowercased with
+# the trailing dot stripped).
+_ABBREV = {
+    "e.g", "i.e", "etc", "cf", "vs", "al", "no", "fig",
+    "dr", "mr", "ms", "inc", "ltd", "jr", "sr",
+}
+
+
+def _ventilate_segment(seg: str) -> str:
+    def replace_boundary(match: re.Match) -> str:
+        mark = match.start()
+        prev = seg[mark - 1] if mark > 0 else ""
+        # A number, a bare-digit, or an ellipsis dot is not a sentence end.
+        if not prev or prev.isspace() or prev.isdigit() or prev == ".":
+            return match.group(0)
+        tail = re.search(r"[A-Za-z.]+$", seg[: mark + 1])
+        if tail and tail.group(0).rstrip(".").lower() in _ABBREV:
+            return match.group(0)
+        return seg[mark] + "\n"
+
+    return _SENT_BOUNDARY_RE.sub(replace_boundary, seg)
+
+
+def _split_prose_line(line: str) -> str:
+    parts = line.split("`")
+    for even in range(0, len(parts), 2):  # segments outside backtick code spans
+        parts[even] = _ventilate_segment(parts[even])
+    return "`".join(parts)
+
+
+def _ventilate_prose(markdown: str) -> str:
+    """Break prose paragraphs into one sentence per line. Idempotent: a line
+    already holding a single sentence has no internal boundary to split."""
+    lines = markdown.split("\n")
+    mask = _code_line_mask(lines)
+    for i, line in enumerate(lines):
+        if mask[i]:  # frontmatter / fenced code
+            continue
+        if not line or line != line.lstrip():  # blank or indented continuation
+            continue
+        if (
+            _HEADING_RE.match(line)
+            or line.startswith("|")
+            or line.startswith(">")
+            or _LIST_LINE_RE.match(line)
+        ):
+            continue
+        lines[i] = _split_prose_line(line)
+    return "\n".join(lines)
+
+
 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
@@ -500,7 +560,8 @@ def render(
     try:
         template = env.get_template(template_path.name)
         rendered = template.render(**data)
-        return _inject_index_and_anchors(rendered, dictionary)
+        rendered = _inject_index_and_anchors(rendered, dictionary)
+        return _ventilate_prose(rendered)
     except I18nError as exc:
         raise FinalReportRenderError(
             f"i18n lookup failed while rendering {template_path.name}: {exc}"

package/runtime/python/okstra_ctl/report_views.py

@@ -399,7 +399,9 @@ def _markdown_to_html(
             para_lines.append(ln)
             i += 1
         if para_lines:
-            out.append("<p>" + _inline(" ".join(para_lines)) + "</p>")
+            # The renderer's prose ventilation puts one sentence per source
+            # line; join with <br> so those breaks survive into the HTML.
+            out.append("<p>" + _inline("<br>".join(para_lines)) + "</p>")
 
     return "\n".join(out), headings
 

package/runtime/validators/validate-run.py

@@ -78,7 +78,10 @@ from okstra_ctl.worker_prompt_contract import (  # noqa: E402
     PromptRecord,
     validate_initial_prompt_records,
 )
-from okstra_ctl.convergence_engine import validate_final_state  # noqa: E402
+from okstra_ctl.convergence_engine import (  # noqa: E402
+    grouped_input_digest,
+    validate_final_state,
+)
 
 TERMINAL_STATUSES = {"completed", "timeout", "error", "not-run"}
 ATTEMPTED_STATUSES = {"completed", "timeout", "error"}
@@ -1609,6 +1612,14 @@ def _validate_conformance(
                 f"conformance gate BLOCKING for stage {stage_key}: "
                 "requires=[] is declaration/contract trouble and cannot be waived"
             )
+        if entry.get("requires") and entry.get("exemption"):
+            failures.append(
+                f"conformance gate BLOCKING for stage {stage_key}: "
+                f"a stage that declares a gated surface (requires="
+                f"{entry.get('requires')}) cannot be exempted — submit a real "
+                "conformance result or record a user-acknowledged waiver. See "
+                "docs/superpowers/specs/2026-06-07-stage-conformance-qa-design.md §7.1."
+            )
     results = _load_conformance_results(qa_dir, scoped)
     for verdict in evaluate_conformance(scoped, results):
         if verdict.status == "ADVISORY":
@@ -5081,6 +5092,292 @@ def _validate_convergence_states(run_dir, failures) -> None:
         )
 
 
+def _nonempty_string(value) -> bool:
+    """True for a non-blank string, matching the schema's `\\S` pattern."""
+    return isinstance(value, str) and value.strip() != ""
+
+
+# Round-0 grouping filename: `convergence-groups-<task-type>-<seq>.json`. The
+# `<task-type>-<seq>` suffix is shared verbatim with the worker-result and
+# working-state basenames, so capture it as one token to reconstruct both.
+_CONVERGENCE_GROUPS_BASENAME_RE = re.compile(
+    r"^convergence-groups-(?P<suffix>[a-z][a-z-]*?-\d{3})\.json$"
+)
+
+
+def _convergence_group_claims(document) -> list[tuple[str, str, str]] | None:
+    """Extract `(findingId, worker, itemId)` provenance claims from a grouping.
+
+    Returns ``None`` when the document does not match the convergence-groups
+    schema shape closely enough to read its provenance fields safely — the
+    caller refuses to judge such a file. Otherwise returns the deduplicated
+    claims drawn from every group's ``sourceItems[]`` and ``discoveredBy`` map.
+    """
+    if not isinstance(document, dict) or not isinstance(document.get("groups"), list):
+        return None
+    claims: list[tuple[str, str, str]] = []
+    seen: set[tuple[str, str, str]] = set()
+    for group in document["groups"]:
+        if not isinstance(group, dict):
+            return None
+        finding_id = group.get("findingId")
+        source_items = group.get("sourceItems")
+        discovered_by = group.get("discoveredBy")
+        if (
+            not _nonempty_string(finding_id)
+            or not isinstance(source_items, list)
+            or not isinstance(discovered_by, dict)
+        ):
+            return None
+        pairs: list[tuple[object, object]] = []
+        for item in source_items:
+            if not isinstance(item, dict):
+                return None
+            pairs.append((item.get("worker"), item.get("itemId")))
+        for worker, discovery in discovered_by.items():
+            if not isinstance(discovery, dict):
+                return None
+            pairs.append((worker, discovery.get("itemId")))
+        for worker, item_id in pairs:
+            if not _nonempty_string(worker) or not _nonempty_string(item_id):
+                return None
+            claim = (finding_id, worker, item_id)
+            if claim not in seen:
+                seen.add(claim)
+                claims.append(claim)
+    return claims
+
+
+def _convergence_groups_digest_ok(state_dir, suffix: str, document: dict) -> bool:
+    """False only when a recorded groupsDigest exists and no longer matches.
+
+    ``okstra convergence seed`` pins ``grouped_input_digest`` of the grouping
+    into the working state. When that record is present and disagrees with the
+    on-disk grouping, the file was tampered with or written out of band — not
+    evidence of fabrication — so the caller refuses to judge it. A missing
+    working state or missing digest means judge the file as parsed.
+    """
+    work_path = state_dir / f"convergence-work-{suffix}.json"
+    try:
+        work = json.loads(work_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return True
+    recorded = work.get("groupsDigest") if isinstance(work, dict) else None
+    if not _nonempty_string(recorded):
+        return True
+    return grouped_input_digest(document) == recorded
+
+
+def _read_canonical_worker_result(worker_results_dir, worker: str, suffix: str):
+    """Return the `<worker>-<suffix>.md` text, or ``None`` when it is not a
+    resolvable file directly inside ``worker-results/`` (missing, unreadable,
+    or a worker slug that is not a single path component)."""
+    candidate = worker_results_dir / f"{worker}-{suffix}.md"
+    try:
+        if candidate.resolve().parent != worker_results_dir.resolve():
+            return None
+        return candidate.read_text(encoding="utf-8")
+    except (OSError, ValueError):
+        return None
+
+
+def _id_occurs_wordbounded(text: str, item_id: str) -> bool:
+    """True when `item_id` occurs as a literal not flanked by another
+    identifier char, so `F-7` matches neither `F-70` nor `xF-7`."""
+    pattern = r"(?<![0-9A-Za-z_-])" + re.escape(item_id) + r"(?![0-9A-Za-z_-])"
+    return re.search(pattern, text) is not None
+
+
+def _validate_convergence_group_provenance(run_dir, failures) -> None:
+    """Every source item a round-0 grouping cites must exist in the worker file.
+
+    The lead mints its own finding IDs, but each ``sourceItems[].itemId`` and
+    ``discoveredBy.<worker>.itemId`` is copied verbatim from a worker's own
+    result. A grouping that cites ``codex-worker:F-007`` when codex never wrote
+    F-007 is a fabricated provenance link the final report cannot expose. This
+    replays that one claim: the cited item ID must occur, word-boundary
+    anchored, in the worker's canonical result file.
+
+    A validator failure blocks user approval, so unjudgeable input is skipped
+    silently: no groups file, unreadable/malformed JSON, a groups file that
+    fails the schema shape, a missing worker result file (provider-unavailable
+    substitution is legitimate), or a recorded groupsDigest that no longer
+    matches.
+    """
+    from pathlib import Path as _Path
+
+    state_dir = _Path(run_dir) / "state"
+    worker_results_dir = _Path(run_dir) / "worker-results"
+    if not state_dir.is_dir() or not worker_results_dir.is_dir():
+        return
+    for groups_path in sorted(state_dir.glob("convergence-groups-*.json")):
+        match = _CONVERGENCE_GROUPS_BASENAME_RE.match(groups_path.name)
+        if match is None:
+            continue
+        suffix = match.group("suffix")
+        try:
+            document = json.loads(groups_path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        claims = _convergence_group_claims(document)
+        if claims is None:
+            continue
+        if not _convergence_groups_digest_ok(state_dir, suffix, document):
+            continue
+        contents: dict[str, str | None] = {}
+        for finding_id, worker, item_id in claims:
+            if worker not in contents:
+                contents[worker] = _read_canonical_worker_result(
+                    worker_results_dir, worker, suffix
+                )
+            text = contents[worker]
+            if text is None or _id_occurs_wordbounded(text, item_id):
+                continue
+            failures.append(
+                f"convergence groups `{groups_path.name}` group {finding_id} "
+                f"cites source item `{worker}:{item_id}`, but that ID does not "
+                f"occur in the worker's result file `{worker}-{suffix}.md` — a "
+                "grouping may not invent a provenance link to an item the "
+                "worker never reported."
+            )
+
+
+# Reverify-prompt basename: `<role-slug>-reverify-r<N>-<task-type>-<seq>.md`.
+# The role slug ends in `-worker` like the worker-result files, but the round
+# plan's `dispatches[].worker` may carry either that full slug or the bare
+# provider token (`claude` vs `claude-worker`), depending on how the roster was
+# seeded — worker resolution below accepts both. `-reverify-r` never occurs
+# inside a slug, so the non-greedy slug capture stops at that literal anchor.
+_REVERIFY_PROMPT_BASENAME_RE = re.compile(
+    r"^(?P<slug>[a-z][a-z0-9-]*?)-reverify-r(?P<round>\d+)"
+    r"-(?P<task_type>[a-z][a-z-]*?)-(?P<seq>\d{3})\.md$"
+)
+
+# The reverify prompt's finding identifier is the lead-minted `### F-NNN` /
+# `### C-NNN` H3 heading inside the `## Findings to verify` block. The older
+# `### VF-N (origin ...)` / `G-NNN` heading shape this token regex deliberately
+# does not match, so historical prompts parse zero ids and are skipped.
+_FINDINGS_TO_VERIFY_HEADING_RE = re.compile(r"^##\s+Findings to verify\s*$")
+_TWO_HASH_HEADING_RE = re.compile(r"^##\s")
+_FINDING_HEADING_TOKEN_RE = re.compile(r"^###\s+(F-\d+|C-\d+)")
+
+
+def _reverify_prompt_finding_ids(content: str) -> set[str] | None:
+    """Distinct `### F-NNN`/`### C-NNN` tokens in the `## Findings to verify`
+    block, or ``None`` when the prompt has no such block.
+
+    The `## Response format` section re-echoes the same headings, so the block
+    is bounded at the next `## ` heading and the tokens are collected into a
+    set — order and re-echoed duplicates are irrelevant because votes are keyed
+    by findingId. An empty set means the block exists but yielded no recognized
+    heading (the historical `VF-N`/`G-NNN` shape); the caller skips both.
+    """
+    lines = content.splitlines()
+    start = None
+    for index, line in enumerate(lines):
+        if _FINDINGS_TO_VERIFY_HEADING_RE.match(line):
+            start = index + 1
+            break
+    if start is None:
+        return None
+    ids: set[str] = set()
+    for line in lines[start:]:
+        if _TWO_HASH_HEADING_RE.match(line):
+            break  # next `## ` section (e.g. `## Response format`) ends the block
+        match = _FINDING_HEADING_TOKEN_RE.match(line)
+        if match:
+            ids.add(match.group(1))
+    return ids
+
+
+def _plan_dispatch_finding_ids(plan, prompt_slug: str) -> set[str] | None:
+    """The `findingIds` set of the single `dispatches[]` row the prompt slug
+    resolves to, or ``None`` when the plan shape is malformed or the slug does
+    not resolve to exactly one row (refuse to judge either way).
+
+    A prompt slug `claude-worker` matches a row whose `worker` is `claude-worker`
+    (exact) or `claude` (bare token, `worker + "-worker" == slug`). The round
+    plan has no JSON schema, so the `dispatches[]` shape is validated defensively.
+    """
+    if not isinstance(plan, dict):
+        return None
+    dispatches = plan.get("dispatches")
+    if not isinstance(dispatches, list):
+        return None
+    matched: list[set[str]] = []
+    for row in dispatches:
+        if not isinstance(row, dict):
+            return None
+        worker = row.get("worker")
+        finding_ids = row.get("findingIds")
+        if not _nonempty_string(worker) or not isinstance(finding_ids, list):
+            return None
+        if any(not _nonempty_string(fid) for fid in finding_ids):
+            return None
+        if worker == prompt_slug or f"{worker}-worker" == prompt_slug:
+            matched.append(set(finding_ids))
+    if len(matched) != 1:
+        return None
+    return matched[0]
+
+
+def _validate_reverify_prompt_matches_plan(run_dir, failures) -> None:
+    """Each reverify prompt must show exactly the findings its plan row assigned.
+
+    `okstra convergence apply-round` checks *who* voted (`votes ⊆ plan`), but
+    nothing checks that the reverify *prompt* carried the findings the plan
+    assigned. A prompt-generation bug or a tampered prompt that drops or adds a
+    `### F-NNN` heading relative to `dispatches[].findingIds` goes undetected,
+    and a vote can be attributed to a finding the worker was never shown. This
+    replays `plan == prompt`, which with the engine's check yields
+    `votes ⊆ what-was-shown`. It stays independent of the engine's own check.
+
+    A validator failure blocks user approval, so any unjudgeable input is
+    skipped silently: no paired plan file for the prompt's (round, task-type,
+    seq) — which also excludes a superseded plan whose seq/task-type differs;
+    no recognizable `## Findings to verify` block or zero headings (guards the
+    historical `VF-N`/`G-NNN` formats); a worker slug that resolves to other
+    than exactly one `dispatches[]` row; and an unreadable/malformed plan.
+    """
+    from pathlib import Path as _Path
+
+    run_dir = _Path(run_dir)
+    prompts_dir = run_dir / "prompts"
+    state_dir = run_dir / "state"
+    if not prompts_dir.is_dir() or not state_dir.is_dir():
+        return
+    for prompt_path in sorted(prompts_dir.glob("*-reverify-r*.md")):
+        match = _REVERIFY_PROMPT_BASENAME_RE.match(prompt_path.name)
+        if match is None:
+            continue
+        round_n = match.group("round")
+        plan_path = state_dir / (
+            f"convergence-round-{round_n}-plan-"
+            f"{match.group('task_type')}-{match.group('seq')}.json"
+        )
+        if not plan_path.is_file():
+            continue  # no paired plan (~96% of artifacts) — never infer from the prompt
+        try:
+            content = prompt_path.read_text(encoding="utf-8")
+            plan = json.loads(plan_path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        prompt_ids = _reverify_prompt_finding_ids(content)
+        if not prompt_ids:  # None (no block) or empty set (no F-/C- headings)
+            continue
+        plan_ids = _plan_dispatch_finding_ids(plan, match.group("slug"))
+        if plan_ids is None or prompt_ids == plan_ids:
+            continue
+        failures.append(
+            f"reverify prompt `{prompt_path.name}` (round {round_n}, worker "
+            f"`{match.group('slug')}`) does not show the findings its plan row "
+            f"assigned: in the plan but not the prompt {sorted(plan_ids - prompt_ids)}; "
+            f"in the prompt but not the plan {sorted(prompt_ids - plan_ids)}. The "
+            f"prompt must carry exactly `dispatches[].findingIds` so a vote cannot "
+            f"be attributed to a finding the worker was never shown."
+        )
+
+
 def _validate_requirements_discovery_fanout(run_dir, failures, brief_path=None) -> None:
     """requirements-discovery run 에 fan-out/ 이 있으면 packet+index 를 검증해
     실패를 ``requirements-discovery: `` 접두로 folding 한다. fan-out 이 없으면 no-op.
@@ -5558,6 +5855,8 @@ def main() -> int:
     _validate_convergence_rounds_match_manifest(
         report_path.parent.parent, run_manifest, failures
     )
+    _validate_convergence_group_provenance(report_path.parent.parent, failures)
+    _validate_reverify_prompt_matches_plan(report_path.parent.parent, failures)
     validate_report_views(report_path, failures)
     if task_type == "implementation":
         _validate_missing_qa_categories_recorded(