okstra 0.158.1 → 0.160.0

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -1,4 +1,9 @@
-"""CLI adapter for deterministic implementation-planning item extraction."""
+"""CLI adapter for deterministic implementation-planning item extraction.
+
+`extract` / `validate` own the `P-*` queue; `collect-verdicts` / `apply-verdicts`
+own the round's votes on that queue. Both halves exist so the round's fidelity
+does not depend on a parser the lead re-writes each time.
+"""
 from __future__ import annotations
 
 import argparse
@@ -10,6 +15,7 @@ from typing import Any
 
 from .convergence_store import write_json_atomic
 from .plan_items import PlanItemContractError, extract_plan_items
+from .verdict_blocks import VerdictBlock, VerdictBlockError, parse_verdict_blocks
 
 
 def _load_json_object(path: Path) -> dict[str, Any]:
@@ -49,6 +55,21 @@ def _parser() -> argparse.ArgumentParser:
     validate = commands.add_parser("validate")
     validate.add_argument("--data", type=Path, required=True)
     validate.add_argument("--items", type=Path, required=True)
+    collect = commands.add_parser(
+        "collect-verdicts",
+        help="read this round's worker responses into a verdicts envelope",
+    )
+    collect.add_argument("--result", action="append", default=[], required=True,
+                         metavar="<worker-id>=<path>",
+                         help="one worker's plan-verify result file (repeatable)")
+    collect.add_argument("--items", type=Path, required=True)
+    collect.add_argument("--output", type=Path, required=True)
+    apply_verdicts = commands.add_parser(
+        "apply-verdicts",
+        help="overwrite planBodyVerification.planItems[].verdicts in data.json",
+    )
+    apply_verdicts.add_argument("--data", type=Path, required=True)
+    apply_verdicts.add_argument("--verdicts", type=Path, required=True)
     return parser
 
 
@@ -66,11 +87,154 @@ def _validate(args: argparse.Namespace) -> dict[str, Any]:
     return {"ok": True, "operation": "validate", "path": str(args.items)}
 
 
+def _split_result_arg(raw: str) -> tuple[str, Path]:
+    worker, separator, path = raw.partition("=")
+    if not separator or not worker.strip() or not path.strip():
+        raise PlanItemContractError(
+            f"--result must be <worker-id>=<path>, got: {raw}"
+        )
+    return worker.strip(), Path(path.strip())
+
+
+def _assigned_item_ids(items_path: Path) -> list[str]:
+    envelope = _load_json_object(items_path)
+    items = envelope.get("items")
+    if not isinstance(items, list):
+        raise PlanItemContractError(f"items envelope has no `items` array: {items_path}")
+    ids: list[str] = []
+    for item in items:
+        item_id = item.get("id") if isinstance(item, Mapping) else None
+        if not isinstance(item_id, str) or not item_id:
+            raise PlanItemContractError(f"every item needs an `id`: {items_path}")
+        ids.append(item_id)
+    return ids
+
+
+def _verdict_row(worker: str, block: VerdictBlock) -> dict[str, Any]:
+    """One `planItems[].verdicts[]` row. Optional fields stay absent when empty
+    so the recorded table shows what the worker actually said."""
+    row: dict[str, Any] = {"worker": worker, "verdict": block.verdict}
+    for key, value in (
+        ("breakageKind", block.breakage_kind),
+        ("fixability", block.fixability),
+        ("note", block.note),
+        ("priorDissent", block.prior_dissent),
+    ):
+        if value:
+            row[key] = value
+    return row
+
+
+def _worker_blocks(
+    raw_results: list[str], assigned: set[str]
+) -> list[tuple[str, dict[str, VerdictBlock]]]:
+    """Each worker's parsed response, refusing any queue mismatch.
+
+    A missing vote and an invented item are both silent in a hand-written
+    parser; each is a round scored on a table that does not match the queue.
+    """
+    collected: list[tuple[str, dict[str, VerdictBlock]]] = []
+    for raw in raw_results:
+        worker, path = _split_result_arg(raw)
+        try:
+            blocks = parse_verdict_blocks(path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError) as exc:
+            raise PlanItemContractError(f"cannot read result {path}: {exc}") from exc
+        answered = set(blocks)
+        missing = sorted(assigned - answered)
+        if missing:
+            raise PlanItemContractError(
+                f"worker `{worker}` was assigned {len(assigned)} items but "
+                f"returned no verdict for {missing} — an unanswered item cannot "
+                f"be scored, and dropping it silently is what makes a round look "
+                f"complete when it is not"
+            )
+        unknown = sorted(answered - assigned)
+        if unknown:
+            raise PlanItemContractError(
+                f"worker `{worker}` returned verdicts for {unknown}, which are "
+                f"not in the persisted plan-item queue"
+            )
+        collected.append((worker, blocks))
+    return collected
+
+
+def _collect_verdicts(args: argparse.Namespace) -> dict[str, Any]:
+    assigned = _assigned_item_ids(args.items)
+    collected = _worker_blocks(args.result, set(assigned))
+    envelope = {
+        "schemaVersion": "1.0",
+        "taskType": "implementation-planning",
+        "planItems": [
+            {
+                "id": item_id,
+                "verdicts": [
+                    _verdict_row(worker, blocks[item_id])
+                    for worker, blocks in collected
+                ],
+            }
+            for item_id in assigned
+        ],
+    }
+    write_json_atomic(args.output, envelope)
+    return {"ok": True, "operation": "collect-verdicts", "path": str(args.output)}
+
+
+def _plan_body_items(data: dict[str, Any], data_path: Path) -> list[dict[str, Any]]:
+    verification = _planning(data).get("planBodyVerification")
+    if not isinstance(verification, Mapping):
+        raise PlanItemContractError(
+            f"implementationPlanning.planBodyVerification must be an object: {data_path}"
+        )
+    items = verification.get("planItems")
+    if not isinstance(items, list):
+        raise PlanItemContractError(
+            f"planBodyVerification.planItems must be an array: {data_path}"
+        )
+    return items
+
+
+def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
+    data = _load_json_object(args.data)
+    incoming = _load_json_object(args.verdicts).get("planItems")
+    if not isinstance(incoming, list):
+        raise PlanItemContractError("verdicts envelope has no `planItems` array")
+    rows = {
+        item["id"]: item.get("verdicts", [])
+        for item in incoming
+        if isinstance(item, Mapping) and isinstance(item.get("id"), str)
+    }
+    recorded = _plan_body_items(data, args.data)
+    known = {item.get("id") for item in recorded if isinstance(item, Mapping)}
+    missing = sorted(item_id for item_id in rows if item_id not in known)
+    if missing:
+        raise PlanItemContractError(
+            f"the report's planBodyVerification has no row for {missing} — the "
+            f"gate is re-derived from that table, so a verdict with nowhere to "
+            f"land would be scored as if it were never cast"
+        )
+    for item in recorded:
+        if isinstance(item, Mapping) and item.get("id") in rows:
+            # Overwrite, never merge: the contract records one round at a time,
+            # and a merged table lets a previous round's votes keep voting.
+            item["verdicts"] = rows[item["id"]]
+    write_json_atomic(args.data, data)
+    return {"ok": True, "operation": "apply-verdicts", "path": str(args.data)}
+
+
+_HANDLERS = {
+    "extract": _extract,
+    "validate": _validate,
+    "collect-verdicts": _collect_verdicts,
+    "apply-verdicts": _apply_verdicts,
+}
+
+
 def main(argv: list[str] | None = None) -> int:
     args = _parser().parse_args(argv)
     try:
-        result = _extract(args) if args.command == "extract" else _validate(args)
-    except (PlanItemContractError, OSError, ValueError) as exc:
+        result = _HANDLERS[args.command](args)
+    except (PlanItemContractError, VerdictBlockError, OSError, ValueError) as exc:
         print(f"plan-items: {exc}", file=sys.stderr)
         return 2
     print(json.dumps(result, ensure_ascii=False, indent=2))

package/runtime/python/okstra_ctl/profile_show.py

@@ -0,0 +1,134 @@
+"""Read-only flattened view of a phase profile (`okstra profile show`).
+
+A profile is assembled from three places — the top-level body, its
+`{{INCLUDE:}}` targets, and the lazy-read sidecars the body's own table names —
+so grepping the top-level file and finding nothing does not mean the rule is
+absent. This prints the whole thing, so one grep answers "does this task-type
+cover X".
+
+Read-only is the point, not a nicety: `render-bundle` would answer the same
+question, but it writes a manifest and registers the run in `recent.jsonl`.
+That side effect is exactly why it cannot be used to look something up.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+from pathlib import Path
+
+from .paths import find_asset_root
+from .run import PrepareError, _expand_profile_includes
+
+_PROFILES_REL = ("prompts", "profiles")
+
+# The sidecar table spells its targets as inline-code repo-relative paths, e.g.
+# `prompts/profiles/_implementation-executor.md`. Reading the list from the
+# profile body rather than hard-coding it here is deliberate: a list in code
+# goes stale the moment a profile adds a sidecar, and does so silently.
+_SIDECAR_RE = re.compile(r"`(prompts/profiles/_[\w-]+\.md)`")
+
+
+def workspace_root(start: Path | None = None) -> Path:
+    """Locate the runtime root that carries the `prompts/profiles` tree."""
+    root = find_asset_root(_PROFILES_REL, start=start, is_present=Path.is_dir)
+    if root is not None:
+        return root
+
+    raise PrepareError(
+        "could not locate prompts/profiles. Set OKSTRA_HOME or run from a "
+        "checkout that contains prompts/profiles/."
+    )
+
+
+def profile_path(root: Path, task_type: str) -> Path:
+    path = root.joinpath(*_PROFILES_REL, f"{task_type}.md")
+    if not path.is_file():
+        raise PrepareError(f"unknown task-type: {task_type} (no {path})")
+    return path
+
+
+def sidecar_bodies(root: Path, profile_text: str) -> list[str]:
+    """Every lazy-read sidecar reachable from the profile body, breadth-first.
+
+    The walk runs to a fixpoint because sidecars name sidecars of their own:
+    `_implementation-executor.md` points at the coding-conventions preflight,
+    the diff-review sweep, and the completion self-check. Stopping after one
+    hop would rebuild the very false negative this command exists to prevent,
+    one level down.
+
+    Each body is expanded rather than read raw, so nested `{{INCLUDE:}}`
+    directives resolve and the maintainer-only HTML comments drop out — the
+    same treatment the lead's rendered profile gets.
+    """
+    bodies: list[str] = []
+    seen: set[str] = set()
+    pending = list(dict.fromkeys(_SIDECAR_RE.findall(profile_text)))
+    while pending:
+        relative = pending.pop(0)
+        if relative in seen:
+            continue
+        seen.add(relative)
+        path = root / relative
+        if not path.is_file():
+            continue
+        body = _expand_profile_includes(path)
+        bodies.append(f"\n\n<!-- lazy-read sidecar: {relative} -->\n\n{body}")
+        pending.extend(ref for ref in _SIDECAR_RE.findall(body) if ref not in seen)
+    return bodies
+
+
+def render(root: Path, task_type: str, *, resolved: bool) -> str:
+    path = profile_path(root, task_type)
+    if not resolved:
+        return path.read_text(encoding="utf-8")
+    expanded = _expand_profile_includes(path)
+    return expanded + "".join(sidecar_bodies(root, expanded))
+
+
+def _write_stdout(text: str) -> None:
+    """Write the profile, tolerating a reader that stops early.
+
+    The command's whole purpose is to be piped into `grep` or `head`, and both
+    close the pipe as soon as they have enough. Without this, that normal usage
+    ends in a BrokenPipeError traceback — and the interpreter raises a second
+    one when it flushes stdout at shutdown, which is why the fd is redirected
+    to devnull rather than merely swallowing the first exception.
+    """
+    try:
+        sys.stdout.write(text)
+        sys.stdout.flush()
+    except BrokenPipeError:
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        try:
+            os.dup2(devnull, sys.stdout.fileno())
+        finally:
+            os.close(devnull)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="okstra profile show",
+        description="Print a phase profile, optionally fully resolved (read-only).",
+    )
+    parser.add_argument("command", choices=("show",))
+    parser.add_argument("task_type")
+    parser.add_argument(
+        "--resolved",
+        action="store_true",
+        help="expand {{INCLUDE:}} targets and append the lazy-read sidecars",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        text = render(workspace_root(), args.task_type, resolved=args.resolved)
+    except PrepareError as exc:
+        print(f"profile show: {exc}", file=sys.stderr)
+        return 2
+    _write_stdout(text)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/recap.py

@@ -11,7 +11,9 @@ import json
 import sys
 from pathlib import Path
 
+from okstra_ctl.clarification_items import sidecar_answers, user_response_sidecars
 from okstra_ctl.ids import slugify_task_segment
+from okstra_ctl.incremental_scope import preview_link_availability_for_report
 from okstra_ctl.paths import task_timeline_file
 from okstra_project import read_task_key
 from okstra_ctl.run_context import dir_flock
@@ -33,6 +35,63 @@ def _load_timeline(task_root: Path) -> list[dict]:
 
 
 
+_STRUCTURAL_CHANGE_NOTE = (
+    "An answer that overturns the selected option, restructures the Stage Map, "
+    'or changes the recommended approach requires --full-reason "<what changes '
+    'and how>". The back-trace resolves stages; it cannot judge whether the '
+    "plan's shape survived, so that call is the lead's and must be declared."
+)
+
+
+def _latest_planning_report(runs: list[dict], project_root: Path) -> Path | None:
+    """The most recent `implementation-planning` report still on disk."""
+    for run in reversed(runs):
+        if not isinstance(run, dict):
+            continue
+        if run.get("taskType") != "implementation-planning":
+            continue
+        relative = str(run.get("reportPath") or "")
+        if not relative:
+            continue
+        report = project_root / relative
+        if report.is_file():
+            return report
+    return None
+
+
+def rerun_readiness(project_root: Path, runs: list[dict]) -> dict | None:
+    """What the next clarification re-run needs, assembled from disk.
+
+    Every field is derivable before the run starts, and each one used to live
+    somewhere else: the flag value in the lead prompt (read only *after* the
+    run begins), the answered ids in sidecars, the re-verification mode nowhere
+    at all until `incremental-scope --preview`. Scattering them is why the user
+    had to ask for each one instead of being told.
+
+    ``None`` when nothing is waiting to be carried — no planning report, or no
+    answered clarification beside it.
+    """
+    report = _latest_planning_report(runs, project_root)
+    if report is None:
+        return None
+    answered = sorted(sidecar_answers(report))
+    if not answered:
+        return None
+    return {
+        "sourceReport": project_rel(report, project_root),
+        "answeredClarifications": answered,
+        "answeredClarificationsCsv": ",".join(answered),
+        "sidecars": [
+            project_rel(sidecar, project_root)
+            for sidecar in user_response_sidecars(report)
+        ],
+        "reverifyPreview": preview_link_availability_for_report(
+            report, set(answered)
+        ),
+        "structuralChangeNote": _STRUCTURAL_CHANGE_NOTE,
+    }
+
+
 def assemble_recap(task_root: Path, project_root: Path) -> dict:
     runs = _load_timeline(task_root)
     transitions = []
@@ -62,6 +121,10 @@ def assemble_recap(task_root: Path, project_root: Path) -> dict:
         "runCount": len(runs),
         "transitions": transitions,
         "latestPhaseStates": latest_states,
+        # `null` when nothing is waiting to be carried — the key is always
+        # present so a consumer can tell "no re-run pending" from "this recap
+        # predates the block".
+        "rerunReadiness": rerun_readiness(project_root, runs),
     }
 
 

package/runtime/python/okstra_ctl/render_final_report.py

@@ -52,10 +52,12 @@ from okstra_ctl.final_report_schema import (
 from okstra_ctl.i18n import I18nError, SUPPORTED_LANGS, load_dictionary, make_jinja_global
 from okstra_ctl.md_table import UNESCAPED_PIPE_RE, to_cell_text
 from okstra_ctl.models import UnknownModelError, resolve_model_metadata
+from okstra_ctl.paths import find_asset_root
 from okstra_ctl.report_contract import TASK_TYPE_DATA_PROPERTY, markdown_template_for
 from okstra_ctl.report_markdown import ReportSections
 from okstra_ctl.schema_excerpt import excerpt_cut_from_version
 from okstra_ctl.seeding import installed_version
+from okstra_ctl.usage_cells import format_duration_ms, format_int, format_usd
 
 
 TEMPLATE_BY_SCHEMA_VERSION = {
@@ -84,43 +86,6 @@ class FinalReportRenderError(RuntimeError):
     """
 
 
-def _format_int(value: Any) -> str:
-    if value is None or not isinstance(value, (str, int, float)):
-        return "--"
-    try:
-        return f"{int(value):,}"
-    except (TypeError, ValueError):
-        return "--"
-
-
-def _format_usd(value: Any) -> str:
-    if value is None or not isinstance(value, (str, int, float)):
-        return "--"
-    try:
-        return f"${float(value):.2f}"
-    except (TypeError, ValueError):
-        return "--"
-
-
-def _format_duration_ms(value: Any) -> str:
-    if value is None or not isinstance(value, (str, int, float)):
-        return "--"
-    try:
-        ms = int(value)
-    except (TypeError, ValueError):
-        return "--"
-    # A negative elapsed time is nonsensical (clock skew between start/end
-    # timestamps); divmod would otherwise produce a malformed "-1m 59s".
-    if ms < 0:
-        return "--"
-    total_seconds = ms // 1000
-    hours, remainder = divmod(total_seconds, 3600)
-    minutes, seconds = divmod(remainder, 60)
-    if hours:
-        return f"{hours}h {minutes:02d}m {seconds:02d}s"
-    return f"{minutes}m {seconds:02d}s"
-
-
 def _yaml_scalar(value: Any) -> str:
     """Serialize a scalar for the YAML frontmatter block.
 
@@ -555,9 +520,9 @@ def _build_environment(template_dir: Path) -> Environment:
         lstrip_blocks=True,
         keep_trailing_newline=True,
     )
-    env.filters["format_int"] = _format_int
-    env.filters["format_usd"] = _format_usd
-    env.filters["format_duration_ms"] = _format_duration_ms
+    env.filters["format_int"] = format_int
+    env.filters["format_usd"] = format_usd
+    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
@@ -730,17 +695,9 @@ def find_default_template(start: Path | None = None) -> Path:
 
     Raises ``FinalReportRenderError`` if neither path is present.
     """
-    okstra_home = os.environ.get("OKSTRA_HOME")
-    if okstra_home:
-        candidate = Path(okstra_home).joinpath(*DEFAULT_TEMPLATE_REL)
-        if candidate.is_file():
-            return candidate
-
-    here = Path(start or __file__).resolve()
-    for parent in [here, *here.parents]:
-        candidate = parent.joinpath(*DEFAULT_TEMPLATE_REL)
-        if candidate.is_file():
-            return candidate
+    root = find_asset_root(DEFAULT_TEMPLATE_REL, start=start)
+    if root is not None:
+        return root.joinpath(*DEFAULT_TEMPLATE_REL)
 
     raise FinalReportRenderError(
         "could not locate final-report.template.md. Set OKSTRA_HOME or "
@@ -760,17 +717,9 @@ def find_default_template_for_data(
             f"unsupported final-report schemaVersion: {version}"
         ) from exc
 
-    okstra_home = os.environ.get("OKSTRA_HOME")
-    if okstra_home:
-        candidate = Path(okstra_home).joinpath(*relative_path)
-        if candidate.is_file():
-            return candidate
-
-    here = Path(start or __file__).resolve()
-    for parent in [here, *here.parents]:
-        candidate = parent.joinpath(*relative_path)
-        if candidate.is_file():
-            return candidate
+    root = find_asset_root(relative_path, start=start)
+    if root is not None:
+        return root.joinpath(*relative_path)
 
     raise FinalReportRenderError(
         f"could not locate {relative_path[-1]}. Set OKSTRA_HOME or run from a "

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

@@ -9,7 +9,12 @@ from markupsafe import Markup, escape
 _INLINE_CODE = re.compile(r"`([^`]+)`")
 _SENTENCE_END = re.compile(r"(?<=[.!?])\s+")
 _SENTENCES_PER_PARAGRAPH = 2
-_ID_TOKEN = re.compile(r"\b[A-Z]{1,3}-\d+\b")
+# `\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)")
 
 
 def _link_ids(escaped: str, anchors: dict) -> str:

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

@@ -14,6 +14,7 @@ from ..final_report_schema import load_schema_for_data, validate
 from ..i18n import HTML_DICTIONARY_REL, load_dictionary, make_jinja_global
 from ..report_translation import overlay
 from ..report_view_artifacts import user_responses_dir_for_report
+from ..usage_cells import format_duration_ms
 from .common import anchor_index
 from .filters import (
     code_evidence,
@@ -26,6 +27,7 @@ from .filters import (
 from .models import HtmlRunMeta
 from .report_index import inject_report_index
 from .router import HtmlRenderError, resolve_html_route
+from .run_usage import run_usage
 
 
 def _sha256(path: Path) -> str:
@@ -47,17 +49,13 @@ def _elapsed_text(elapsed_ms: int | None) -> str | None:
     """Render a run duration, or nothing when there is none to render.
 
     A run whose team-state never recorded timestamps has no measured duration;
-    printing "0m" would claim it finished instantly.
+    printing "0m" would claim it finished instantly. Measured durations go
+    through the same formatter as the per-agent cells below, so the header and
+    the run-cost table do not spell one quantity two ways.
     """
     if not elapsed_ms or elapsed_ms < 0:
         return None
-    minutes, seconds = divmod(round(elapsed_ms / 1000), 60)
-    hours, minutes = divmod(minutes, 60)
-    if hours:
-        return f"{hours}h {minutes}m"
-    if minutes:
-        return f"{minutes}m {seconds}s"
-    return f"{seconds}s"
+    return format_duration_ms(elapsed_ms)
 
 
 def _report_meta(data: dict, run_meta: HtmlRunMeta) -> dict[str, object]:
@@ -152,6 +150,9 @@ def render_v2_html_view(
         "dataSha256": _sha256(data_path),
         "markdownSha256": _sha256(markdown_path),
         "clarificationItems": data.get("clarificationItems", []),
+        # Every task type ends with the same run-cost section, so it is bound
+        # here rather than in ten view models that would each rebuild it.
+        "runUsage": run_usage(data),
         "css": (root / "html/assets/base.css").read_text(encoding="utf-8"),
         "js": response_js + "\n" + base_js,
     }