okstra 0.171.0 → 0.173.0

package/runtime/python/okstra_ctl/report_contract.py

@@ -9,6 +9,7 @@ PUBLIC_REPORT_TASK_TYPES = (
     "requirements-discovery",
     "improvement-discovery",
     "error-analysis",
+    "implementation-option-selection",
     "project-analysis",
     "feature-analysis",
     "change-impact-analysis",
@@ -22,6 +23,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 +65,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 +97,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 +124,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

@@ -1,10 +1,10 @@
 """Phase 7 report post-processing — the single reference point.
 
 Phase 7 turns a Phase 6 final-report data.json into shippable artifacts through
-five ordered steps: English-SSOT verification, usage 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.
+six ordered steps: activity projection, English-SSOT verification, usage
+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.
 
 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 —
@@ -25,11 +25,13 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Callable, Mapping, Sequence
 
+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 .dispatch_state import DispatchError, link_agent_dispatch_result
 
 
+STEP_PROJECT_ACTIVITY = "project-activity"
 STEP_CHECK_SOURCE = "check-source"
 STEP_TOKEN_USAGE = "token-usage"
 STEP_RENDER_VIEWS = "render-views"
@@ -37,6 +39,7 @@ STEP_SPAWN_FOLLOWUPS = "spawn-followups"
 STEP_VALIDATE_RUN = "validate-run"
 
 STEP_ORDER = (
+    STEP_PROJECT_ACTIVITY,
     # First, because everything after it derives from the data.json: rendering
     # a Korean SSOT into English chrome, spawning follow-ups from it, and
     # validating it all succeed on a record the next phase cannot read.
@@ -235,6 +238,16 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
     """Assemble the ordered Phase 7 argv list. Order is contractual."""
     markdown_path = ctx.markdown_path
     return [
+        (
+            STEP_PROJECT_ACTIVITY,
+            [
+                "<in-process>",
+                "agent-activity",
+                "project",
+                str(ctx.manifest_path),
+                str(ctx.data_path),
+            ],
+        ),
         (
             STEP_CHECK_SOURCE,
             [
@@ -349,8 +362,8 @@ def run_finalize(
 
     ``only`` restricts the run to the named steps, preserving contractual
     order. The last step (`validate-run`) is the one that usually fails, and
-    re-running the whole sequence to retry it repeats three idempotent steps
-    at full token and wall-clock cost.
+    re-running the whole sequence to retry it repeats every preceding idempotent
+    step at full token and wall-clock cost.
     """
     steps: list[dict[str, Any]] = []
     try:
@@ -372,6 +385,29 @@ def run_finalize(
     for name, command in commands:
         if before_step is not None:
             before_step(name)
+        if name == STEP_PROJECT_ACTIVITY:
+            try:
+                rows = project_agent_activity(
+                    ctx.project_root,
+                    ctx.manifest_path,
+                    ctx.data_path,
+                )
+            except ActivityProjectionError as exc:
+                result = subprocess.CompletedProcess(
+                    command,
+                    1,
+                    "",
+                    str(exc),
+                )
+            else:
+                result = subprocess.CompletedProcess(
+                    command,
+                    0,
+                    json.dumps({"count": len(rows)}),
+                    "",
+                )
+        else:
+            result = None
         if name == STEP_VALIDATE_RUN:
             try:
                 _link_lead_result_for_validation(ctx)
@@ -381,12 +417,13 @@ def run_finalize(
                     "reason": f"lead result linkage failed: {exc}",
                     "steps": steps,
                 }
-        result = subprocess.run(
-            command,
-            cwd=ctx.project_root,
-            text=True,
-            capture_output=True,
-        )
+        if result is None:
+            result = subprocess.run(
+                command,
+                cwd=ctx.project_root,
+                text=True,
+                capture_output=True,
+            )
         steps.append(step_payload(name, command, result))
         if result.returncode != 0:
             return {
@@ -489,7 +526,7 @@ def _parser() -> argparse.ArgumentParser:
         help=(
             "run only these steps (repeatable, contractual order preserved). "
             "Use `--only validate-run` to retry the step that usually fails "
-            "without repeating the three idempotent ones before it."
+            "without repeating the preceding idempotent steps."
         ),
     )
     return parser

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

@@ -85,6 +85,7 @@ def _own_section_ids(data: dict, omitted_fields: tuple[str, ...] = ()) -> set[st
 
     found: set[str] = set()
     _collect_ids(data.get("clarificationItems", []), found)
+    _collect_ids(data.get("agentActivity", []), found)
     property_name = TASK_TYPE_DATA_PROPERTY.get(data.get("header", {}).get("taskType", ""))
     if property_name:
         block = data.get(property_name, {})
@@ -120,9 +121,10 @@ def evidence_index(data: dict) -> dict[str, object]:
 
 def _collect_ids(value: object, found: set[str]) -> None:
     if isinstance(value, dict):
-        row_id = value.get("id")
-        if isinstance(row_id, str) and row_id:
-            found.add(row_id)
+        for key in ("id", "activityId"):
+            row_id = value.get(key)
+            if isinstance(row_id, str) and row_id:
+                found.add(row_id)
         for nested in value.values():
             _collect_ids(nested, found)
     elif isinstance(value, list):

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,26 +104,42 @@ _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)
+    )
+    decision_cards = tuple(
+        row
+        for row in data.get("clarificationItems", [])
+        if isinstance(row, dict)
+        and row.get("blocks") == "approval"
+        and isinstance(row.get("approvalContext"), dict)
+    )
     context = {
         "humanSummary": data["humanSummary"],
         "planning": planning,
-        "narrative": planning["userNarrative"],
+        "narrative": planning.get("userNarrative", {}),
         "stageFigure": figure,
         "approval": approval,
         "openDecisions": [
             row
             for row in data.get("clarificationItems", [])
-            if row.get("blocks") == "approval"
+            if isinstance(row, dict)
+            and row.get("blocks") == "approval"
             and row.get("status") in {"open", "answered"}
         ],
+        "agentActivities": activities,
+        "activityById": {
+            row["activityId"]: row for row in activities if row.get("activityId")
+        },
+        "decisionCards": decision_cards,
         "evidenceIndex": evidence_index(data),
     }
     return HumanReportView(
         "implementation-planning",
         "html/tasks/implementation-planning.template.html",
         context,
-        (figure,),
+        (figure,) if figure is not None else (),
         _OMITTED_FIELDS,
     )

package/runtime/python/okstra_ctl/report_translation.py

@@ -125,8 +125,10 @@ PROSE_KEYS = frozenset({
     "topic",
     "trigger",
     "triggerSignal",
+    "unblockCondition",
     "userChoice",
     "userInput",
+    "userText",
     "verification",
     "verificationMethod",
     "verificationSignal",
@@ -138,6 +140,8 @@ PROSE_KEYS = frozenset({
 # that must stay verbatim to be evidence at all.
 STRUCTURAL_KEYS = frozenset({
     "action",             # implementation.py: _FILE_ACTIONS lookup key
+    "activityId",
+    "activityIds",
     "adapter",
     "affectedId",
     "affectedTarget",
@@ -152,12 +156,15 @@ STRUCTURAL_KEYS = frozenset({
     "capturedHeadSha",
     "carriedForwardFromSeq",
     "carryJson",
+    "checkRefs",
     "clarificationId",
+    "classification",
     "claudeCode",
     "collectorBranch",
     "command",
     "commandOrObservation",
     "commandOrTest",
+    "commands",
     "commitListQuote",
     "complexity",
     "componentId",
@@ -165,14 +172,18 @@ STRUCTURAL_KEYS = frozenset({
     "conformanceTests",
     "coveredBy",
     "createdAt",
+    "cwd",
     "cycle",
     "dataStore",
     "date",
     "dependsOn",
     "diffSummaryQuote",
     "direction",
+    "disposition",
     "dispatches",
     "executorWorktreePath",
+    "evidenceRefs",
+    "exitCode",
     "existingPrUrl",
     "externalSystem",
     "featureId",
@@ -215,6 +226,7 @@ STRUCTURAL_KEYS = frozenset({
     "ownerComponentId",
     "path",
     "planFile",
+    "planItemIds",
     "planStep",
     "prepItemId",
     "project",
@@ -223,11 +235,13 @@ STRUCTURAL_KEYS = frozenset({
     "rawStat",
     "readBoundary",
     "readOnlyCommandLog",
+    "recommendedDisposition",
     "relatedIds",
     "relation",
     "replacedInTest",
     "replacedWith",
     "reportPath",
+    "resultPath",
     "requestKind",
     "requestPath",
     "requestVerbatim",    # the user's own words, quoted as evidence