okstra 0.172.0 → 0.174.0

package/runtime/python/okstra_ctl/render_final_report.py

@@ -12,10 +12,10 @@ columns in the Execution Status table, omitted §4 phase-continuation
 rows, ad-hoc ``## Index`` sections. Routing everything through one
 template + schema cuts those failure modes to zero.
 
-For schema-v1 compatibility, the top-of-report ``## Index`` remains a
-deterministic post-render section built by ``_inject_index_and_anchors``.
-Schema v2 keeps its compact fixed AI-handoff order and does not inject the
-legacy reader index; the task-specific HTML provides the human navigation.
+Rendering never injects a reader index: the AI-handoff markdown keeps its
+compact fixed order and the task-specific HTML provides human navigation.
+``_inject_index_and_anchors`` survives as a standalone pass over an already
+written markdown file, driven by ``scripts/okstra-inject-report-index.py``.
 
 Phase 7 mutation flow: ``okstra-token-usage.py --substitute-data`` fills
 the ``tokenUsage`` and ``executionStatus[].totalTokens`` etc. cells in
@@ -53,7 +53,11 @@ from okstra_ctl.i18n import I18nError, SUPPORTED_LANGS, load_dictionary, make_ji
 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_contract import (
+    CURRENT_REPORT_SCHEMA_VERSION,
+    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
@@ -61,15 +65,15 @@ from okstra_ctl.usage_cells import format_duration_ms, format_int, format_usd
 
 
 TEMPLATE_BY_SCHEMA_VERSION = {
-    "1.0": ("templates", "reports", "final-report.template.md"),
     "2.0": ("templates", "reports", "final-report-v2.template.md"),
 }
-DEFAULT_TEMPLATE_REL = TEMPLATE_BY_SCHEMA_VERSION["1.0"]
+DEFAULT_TEMPLATE_REL = TEMPLATE_BY_SCHEMA_VERSION[CURRENT_REPORT_SCHEMA_VERSION]
 
 TASK_DELIVERABLE_TITLES = {
     "requirements-discovery": "Requirements Discovery",
     "improvement-discovery": "Improvement Discovery",
     "error-analysis": "Error Analysis",
+    "implementation-option-selection": "Implementation Option Selection",
     "project-analysis": "Project Analysis",
     "feature-analysis": "Feature Analysis",
     "change-impact-analysis": "Change Impact Analysis",
@@ -665,14 +669,7 @@ def render(
 
     try:
         template = env.get_template(template_path.name)
-        context = (
-            _ai_markdown_context(data, schema)
-            if data.get("schemaVersion") == "2.0"
-            else _with_optional_defaults(data)
-        )
-        rendered = template.render(**context)
-        if data.get("schemaVersion") == "1.0":
-            rendered = _inject_index_and_anchors(rendered, dictionary)
+        rendered = template.render(**_ai_markdown_context(data, schema))
         return _ventilate_prose(rendered)
     except I18nError as exc:
         raise FinalReportRenderError(
@@ -688,10 +685,10 @@ def find_default_template(start: Path | None = None) -> Path:
     """Locate the bundled final-report template.
 
     Resolution order:
-      1. ``$OKSTRA_HOME/templates/reports/final-report.template.md`` (installed runtime).
-      2. ``<repo>/templates/reports/final-report.template.md`` (in-repo dev runs).
+      1. ``$OKSTRA_HOME/templates/reports/final-report-v2.template.md`` (installed runtime).
+      2. ``<repo>/templates/reports/final-report-v2.template.md`` (in-repo dev runs).
          Repo root is detected by walking up from this file until a
-         ``templates/reports/final-report.template.md`` exists.
+         ``templates/reports/final-report-v2.template.md`` exists.
 
     Raises ``FinalReportRenderError`` if neither path is present.
     """
@@ -700,7 +697,7 @@ def find_default_template(start: Path | None = None) -> Path:
         return root.joinpath(*DEFAULT_TEMPLATE_REL)
 
     raise FinalReportRenderError(
-        "could not locate final-report.template.md. Set OKSTRA_HOME or "
+        "could not locate final-report-v2.template.md. Set OKSTRA_HOME or "
         "run from a checkout that contains templates/reports/."
     )
 

package/runtime/python/okstra_ctl/report_contract.py

@@ -3,12 +3,12 @@ from __future__ import annotations
 
 
 CURRENT_REPORT_SCHEMA_VERSION = "2.0"
-LEGACY_REPORT_SCHEMA_VERSION = "1.0"
 
 PUBLIC_REPORT_TASK_TYPES = (
     "requirements-discovery",
     "improvement-discovery",
     "error-analysis",
+    "implementation-option-selection",
     "project-analysis",
     "feature-analysis",
     "change-impact-analysis",
@@ -22,6 +22,7 @@ TASK_TYPE_DATA_PROPERTY = {
     "requirements-discovery": "requirementsDiscovery",
     "improvement-discovery": "improvementDiscovery",
     "error-analysis": "errorAnalysis",
+    "implementation-option-selection": "implementationOptionSelection",
     "project-analysis": "projectAnalysis",
     "feature-analysis": "featureAnalysis",
     "change-impact-analysis": "changeImpactAnalysis",
@@ -63,6 +64,12 @@ TASK_TYPE_REQUIRED_HUMAN_FIELDS = {
         "errorAnalysis.causeCandidates.falsifyingEvidenceChecked",
         "errorAnalysis.causeCandidates.disproveWith",
     ),
+    "implementation-option-selection": (
+        "implementationOptionSelection.decisionContext.originalRequirementIds",
+        "implementationOptionSelection.rankedOptions.requirementCoverage",
+        "implementationOptionSelection.rankedOptions.coverageSummary",
+        "implementationOptionSelection.recommendedOptionId",
+    ),
     "project-analysis": (
         "projectAnalysis.components",
         "projectAnalysis.entryPoints",
@@ -89,20 +96,12 @@ TASK_TYPE_REQUIRED_HUMAN_FIELDS = {
         "changeImpactAnalysis.securityAndPerformanceImpact",
         "changeImpactAnalysis.planningInputs",
     ),
-    # `validationChecklist` / `rollbackStrategy` are deliberately NOT here. The
-    # planning HTML is the approver's document, and both tables are the
-    # implementer's and auditor's working material — the reasoning is written
-    # into `html/tasks/implementation-planning.template.html` above the
-    # requirement-coverage section, and both still render in the markdown report
-    # (`final-report.template.md` §"Validation Checklist" / §"Rollback
-    # Strategy"). When that split landed the template dropped the sections and
-    # this list kept demanding them, so `validate-report-views.py` failed every
-    # implementation-planning report with nothing a report could do about it.
+    # Legacy plans render option comparison fields; selected-direction plans
+    # render the selected reference, its realization, and exact coverage. The
+    # task-level marker is the only field common to both HTML branches. Each
+    # branch's required details are covered by its schema and renderer tests.
     "implementation-planning": (
-        "implementationPlanning.optionCandidates",
-        "implementationPlanning.tradeoffMatrix",
-        "implementationPlanning.recommendedOption",
-        "implementationPlanning.stageMap",
+        "implementationPlanning",
     ),
     "implementation": (
         "implementation.diffSummary",
@@ -124,6 +123,38 @@ TASK_TYPE_REQUIRED_HUMAN_FIELDS = {
     ),
 }
 
+IMPLEMENTATION_PLANNING_LEGACY_REQUIRED_HUMAN_FIELDS = (
+    "implementationPlanning.optionCandidates",
+    "implementationPlanning.tradeoffMatrix",
+    "implementationPlanning.recommendedOption",
+    "implementationPlanning.stageMap",
+)
+
+IMPLEMENTATION_PLANNING_PLAN_READY_REQUIRED_HUMAN_FIELDS = (
+    "implementationPlanning.selectedDirectionRef",
+    "implementationPlanning.directionRealization",
+    "implementationPlanning.coverageSummary",
+    "implementationPlanning.stageMap",
+    "implementationPlanning.requirementCoverage",
+)
+
+IMPLEMENTATION_PLANNING_INVALIDATED_REQUIRED_HUMAN_FIELDS = (
+    "implementationPlanning.selectedDirectionRef",
+    "implementationPlanning.directionInvalidation",
+    "implementationPlanning.routing",
+)
+
+
+def required_human_fields_for_report(task_type: str, data: dict) -> tuple[str, ...]:
+    if task_type != "implementation-planning":
+        return TASK_TYPE_REQUIRED_HUMAN_FIELDS.get(task_type, ())
+    planning = data.get("implementationPlanning", {})
+    if planning.get("planningContract") != "selected-direction":
+        return IMPLEMENTATION_PLANNING_LEGACY_REQUIRED_HUMAN_FIELDS
+    if planning.get("outcome") == "direction-invalidated":
+        return IMPLEMENTATION_PLANNING_INVALIDATED_REQUIRED_HUMAN_FIELDS
+    return IMPLEMENTATION_PLANNING_PLAN_READY_REQUIRED_HUMAN_FIELDS
+
 
 def report_property_for(task_type: str) -> str:
     try:

package/runtime/python/okstra_ctl/report_finalize.py

@@ -6,6 +6,18 @@ substitution, html view rendering, follow-up task spawning, and run validation.
 The order is load-bearing — rendering before substitution ships `--` token
 cells, and validating before rendering trips the report-views contract.
 
+`token-usage` is the one step whose failure does not stop the sequence, which
+deliberately accepts that first state: its input is the lead session log, so a
+refusal there would otherwise delete every artifact the later steps produce.
+The run does not pass in that state. `validators/validate-run.py` re-collects
+when the recorded usage is all zeros against an `unavailable` session source
+(`_needs_token_autofix`) and refuses the run rather than ship zeroed counts
+(`accuracy-failed`); a legacy v1 report is caught earlier still, by its
+unsubstituted `{{...}}` placeholders, which a v2 report never carries because
+its numeric cells are `null` until this step fills them. Substituting the
+tokens on a later retry then leaves the already-rendered html stale for
+`validators/validate-report-views.py`.
+
 The translation sidecar is NOT one of these steps. `render-views` overlays it,
 so a non-English run dispatches the translator before this sequence starts —
 after verifying the data.json is English, which is why `check-source` is also
@@ -29,6 +41,7 @@ from .agent_activity import ActivityProjectionError, project_agent_activity
 from .dispatch_state import DispatchError, link_agent_dispatch_result
 from .final_report_paths import final_report_data_path, final_report_markdown_path
 from .paths import task_dir, task_manifest_file
+from .session import observe_lead_session
 
 
 STEP_PROJECT_ACTIVITY = "project-activity"
@@ -354,7 +367,14 @@ def run_finalize(
     before_step: Callable[[str], None] | None = None,
     only: Sequence[str] | None = None,
 ) -> dict[str, Any]:
-    """Run the Phase 7 steps in order, stopping at the first non-zero exit.
+    """Run the Phase 7 steps in contractual order.
+
+    A non-zero exit stops the sequence, with one exception: ``token-usage``
+    defers. Its input is the lead session log — state outside this run — so a
+    refusal there is not evidence that the artifacts after it are unwritable.
+    The deferred failure becomes the result's ``reason`` when nothing later
+    fails, and yields to any later failure, which is the step that actually
+    blocked the run.
 
     ``before_step`` fires immediately before each step is spawned, letting an
     adapter settle state the step will read (the Codex adapter marks the report
@@ -366,6 +386,7 @@ def run_finalize(
     step at full token and wall-clock cost.
     """
     steps: list[dict[str, Any]] = []
+    deferred = ""
     try:
         commands = build_commands(ctx)
     except FinalizeError as exc:
@@ -426,11 +447,21 @@ def run_finalize(
             )
         steps.append(step_payload(name, command, result))
         if result.returncode != 0:
-            return {
-                "ok": False,
-                "reason": f"{name} failed with exit code {result.returncode}",
-                "steps": steps,
-            }
+            failure = f"{name} failed with exit code {result.returncode}"
+            # Token collection reads the lead session log, which lives outside
+            # this run. One refusal there (`grandTotalTokens=0`) took the whole
+            # run's output with it: html never rendered, follow-ups never
+            # spawned, and `validate-run` then blocked on `report-views:
+            # missing html artifact`. So this step alone defers instead of
+            # stopping the sequence. It hides nothing — the non-zero exit stays
+            # in `steps`, `ok` stays False, and the closing `validate-run`
+            # still refuses the run.
+            if name == STEP_TOKEN_USAGE:
+                deferred = failure
+                continue
+            return {"ok": False, "reason": failure, "steps": steps}
+    if deferred:
+        return {"ok": False, "reason": deferred, "steps": steps}
     return {"ok": True, "reason": "", "steps": steps}
 
 
@@ -546,6 +577,29 @@ def _step_summary_lines(result: Mapping[str, Any]) -> list[str]:
     return lines
 
 
+def _recovery_step_names(result: Mapping[str, Any]) -> list[str]:
+    """The steps a retry has to re-run: every step from the earliest failure on.
+
+    Naming only the failed steps would prescribe half a recovery. `token-usage`
+    defers, so `render-views` already wrote an html view from unsubstituted
+    data; substituting the tokens on a retry leaves that view stale
+    (`validators/validate-report-views.py` checks `source-sha256` against the
+    md body). And a sequence that stopped early never reached `validate-run`,
+    which is the step that decides whether the run is shippable. Resuming from
+    the earliest failure redoes both while still skipping the prefix that
+    succeeded — the saving `--only` exists for.
+    """
+    failed = {
+        string_value(step.get("name"))
+        for step in (result.get("steps") or [])
+        if step.get("exitCode") != 0
+    }
+    for index, name in enumerate(STEP_ORDER):
+        if name in failed:
+            return list(STEP_ORDER[index:])
+    return []
+
+
 def main(argv: Sequence[str] | None = None) -> int:
     args = _parser().parse_args(argv)
     try:
@@ -553,6 +607,10 @@ def main(argv: Sequence[str] | None = None) -> int:
     except FinalizeError as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2
+    # Phase 7 is the last boundary the lead crosses, and the last chance to add
+    # the generations resume and compaction split it into. It runs ahead of the
+    # sequence because the token-usage step below reads `leadSessionIds`.
+    observe_lead_session(ctx.project_root, ctx.team_state_path)
     result = run_finalize(ctx, only=args.only or None)
     print(json.dumps(result, indent=2, ensure_ascii=False))
     print("finalize steps:", file=sys.stderr)
@@ -560,10 +618,11 @@ def main(argv: Sequence[str] | None = None) -> int:
         print(line, file=sys.stderr)
     if not result["ok"]:
         print(f"error: {result['reason']}", file=sys.stderr)
-        if result.get("steps"):
+        recovery = _recovery_step_names(result)
+        if recovery:
+            flags = " ".join(f"--only {name}" for name in recovery)
             print(
-                "retry just the failing step with "
-                f"`--only {result['steps'][-1].get('name')}`",
+                f"resume the sequence from the earliest failure with `{flags}`",
                 file=sys.stderr,
             )
         return 1

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

@@ -9,7 +9,7 @@ from pathlib import Path
 import okstra_vendor  # noqa: F401  # registers vendored dependency aliases
 from jinja2 import Environment, FileSystemLoader, StrictUndefined, select_autoescape
 
-from ..final_report_paths import translation_sidecar_path
+from ..final_report_paths import final_report_data_path, translation_sidecar_path
 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
@@ -142,11 +142,13 @@ def render_v2_html_view(
     env.filters["paragraphs"] = lambda value: paragraphs(value, anchors)
     response_js = (root / "report.js").read_text(encoding="utf-8")
     base_js = (root / "html/assets/base.js").read_text(encoding="utf-8")
+    source_data = final_report_data_path(Path(run_meta.source_report)).as_posix()
     context = {
         **view.context,
         "runMeta": run_meta,
         "reportMeta": _report_meta(data, run_meta),
         "taskType": view.task_type,
+        "sourceData": source_data,
         "dataSha256": _sha256(data_path),
         "markdownSha256": _sha256(markdown_path),
         "clarificationItems": data.get("clarificationItems", []),
@@ -161,7 +163,7 @@ def render_v2_html_view(
     output_path.write_text(
         inject_report_index(document, label=translate("base.contents")), encoding="utf-8"
     )
-    if context["clarificationItems"]:
+    if context["clarificationItems"] or context.get("directionSelection"):
         # The footer tells the reader to drop the exported file here, so the
         # directory has to exist before they go looking for it.
         user_responses_dir_for_report(data_path).mkdir(parents=True, exist_ok=True)

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

@@ -8,6 +8,9 @@ from .view_models.error_analysis import build_error_analysis_view
 from .view_models.feature_analysis import build_feature_analysis_view
 from .view_models.final_verification import build_final_verification_view
 from .view_models.improvement_discovery import build_improvement_discovery_view
+from .view_models.implementation_option_selection import (
+    build_implementation_option_selection_view,
+)
 from .view_models.implementation import build_implementation_view
 from .view_models.implementation_planning import build_implementation_planning_view
 from .view_models.project_analysis import build_project_analysis_view
@@ -23,6 +26,7 @@ VIEW_BUILDERS = {
     "requirements-discovery": build_requirements_discovery_view,
     "improvement-discovery": build_improvement_discovery_view,
     "error-analysis": build_error_analysis_view,
+    "implementation-option-selection": build_implementation_option_selection_view,
     "project-analysis": build_project_analysis_view,
     "feature-analysis": build_feature_analysis_view,
     "change-impact-analysis": build_change_impact_analysis_view,

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

@@ -0,0 +1,32 @@
+"""Human-first implementation-direction comparison view."""
+from __future__ import annotations
+
+from ..common import evidence_index
+from ..models import HumanReportView
+
+
+def build_implementation_option_selection_view(data: dict) -> HumanReportView:
+    selection = data["implementationOptionSelection"]
+    context = {
+        "humanSummary": data["humanSummary"],
+        "selection": selection,
+        "directionSelection": (
+            selection if selection["mode"] == "candidate-comparison" else None
+        ),
+        "narrative": selection["userNarrative"],
+        "recommendedOption": next(
+            (
+                option
+                for option in selection["rankedOptions"]
+                if option["id"] == selection["recommendedOptionId"]
+            ),
+            None,
+        ),
+        "evidenceIndex": evidence_index(data),
+    }
+    return HumanReportView(
+        task_type="implementation-option-selection",
+        template_name="html/tasks/implementation-option-selection.template.html",
+        context=context,
+        figures=(),
+    )

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

@@ -15,6 +15,8 @@ class PlanApprovalState:
     recommended_option: str
     disabled_reason: str
     blocker_ids: tuple[str, ...]
+    show_option_selector: bool = True
+    reentry_command: str = ""
 
 
 def resolve_recommended_option(rec_name: str, names: tuple[str, ...]) -> str:
@@ -32,6 +34,26 @@ def plan_approval_state(data: dict) -> PlanApprovalState | None:
     planning = data.get("implementationPlanning")
     if not isinstance(planning, dict):
         return None
+    blockers = tuple(
+        row["id"]
+        for row in data.get("clarificationItems", [])
+        if row.get("blocks") == "approval"
+        and row.get("status") in {"open", "answered"}
+    )
+    reason = f"{len(blockers)} approval blocker(s) unresolved" if blockers else ""
+    if planning.get("planningContract") == "selected-direction":
+        if planning.get("outcome") == "direction-invalidated" and not reason:
+            reason = "selected direction invalidated"
+        task_key = (data.get("header") or {}).get("taskKey", "")
+        reentry_command = (
+            f"/okstra-run task-key={task_key} "
+            "task-type=implementation-option-selection"
+            if planning.get("outcome") == "direction-invalidated" and task_key
+            else ""
+        )
+        return PlanApprovalState(
+            (), "", reason, blockers, False, reentry_command
+        )
     names = tuple(
         row["name"]
         for row in planning.get("optionCandidates", [])
@@ -40,13 +62,6 @@ def plan_approval_state(data: dict) -> PlanApprovalState | None:
     if not names:
         return None
     recommended = planning.get("recommendedOption", {}).get("name", "")
-    blockers = tuple(
-        row["id"]
-        for row in data.get("clarificationItems", [])
-        if row.get("blocks") == "approval"
-        and row.get("status") in {"open", "answered"}
-    )
-    reason = f"{len(blockers)} approval blocker(s) unresolved" if blockers else ""
     return PlanApprovalState(
         names,
         resolve_recommended_option(recommended, names),
@@ -89,7 +104,7 @@ _OMITTED_FIELDS = (
 
 def build_implementation_planning_view(data: dict) -> HumanReportView:
     planning = data["implementationPlanning"]
-    figure = _stage_figure(planning)
+    figure = _stage_figure(planning) if planning.get("stageMap") else None
     approval = plan_approval_state(data)
     activities = tuple(
         row for row in data.get("agentActivity", []) if isinstance(row, dict)
@@ -104,7 +119,7 @@ def build_implementation_planning_view(data: dict) -> HumanReportView:
     context = {
         "humanSummary": data["humanSummary"],
         "planning": planning,
-        "narrative": planning["userNarrative"],
+        "narrative": planning.get("userNarrative", {}),
         "stageFigure": figure,
         "approval": approval,
         "openDecisions": [
@@ -125,6 +140,6 @@ def build_implementation_planning_view(data: dict) -> HumanReportView:
         "implementation-planning",
         "html/tasks/implementation-planning.template.html",
         context,
-        (figure,),
+        (figure,) if figure is not None else (),
         _OMITTED_FIELDS,
     )