okstra 0.171.0 → 0.172.0

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/view_models/implementation_planning.py

@@ -91,6 +91,16 @@ def build_implementation_planning_view(data: dict) -> HumanReportView:
     planning = data["implementationPlanning"]
     figure = _stage_figure(planning)
     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,
@@ -100,9 +110,15 @@ def build_implementation_planning_view(data: dict) -> HumanReportView:
         "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(

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

package/runtime/python/okstra_ctl/worker_audit_ledger.py

@@ -10,7 +10,9 @@ so the rules live here rather than inside either one — the same split
 """
 from __future__ import annotations
 
+import json
 import re
+from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -39,6 +41,29 @@ _EVIDENCE_READ_RE = re.compile(
     r"^- Evidence read: `?(?P<path>[^`\n]+?)`?\s*$",
     re.MULTILINE,
 )
+_EVIDENCE_COMMAND_RE = re.compile(
+    r"^- Evidence command:[ \t]*(?P<payload>.*)$", re.MULTILINE
+)
+_EVIDENCE_COMMAND_FIELDS = ("command", "cwd", "exitCode", "outputSummary")
+_EVIDENCE_COMMAND_STRING_FIELDS = ("command", "cwd", "outputSummary")
+_SENSITIVE_KEY_RE = re.compile(
+    r"(?i)(authorization|auth|credential|pass(?:wd|word)?|pwd|token|secret|"
+    r"api[_-]?key|access[_-]?key)"
+)
+_SENSITIVE_TEXT_RE = re.compile(
+    r"(?i)(authorization\s*:\s*\S+|"
+    r"\b(?:[A-Za-z_][A-Za-z0-9_-]*)?(?:auth|credential|pass(?:wd|word)?|pwd|"
+    r"token|secret|api[_-]?key|access[_-]?key)[A-Za-z0-9_-]*\s*=|"
+    r"--[\w-]*(?:auth|credential|pass(?:wd|word)?|pwd|token|secret|"
+    r"api[-_]?key|access[-_]?key)[\w-]*(?:[ =])\S+|"
+    r"\w+://[^\s:/@]+:[^\s@/]+@)"
+)
+_KNOWN_SECRET_RE = re.compile(
+    r"(?:AKIA|ASIA)[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9_]{8,}|"
+    r"github_pat_[A-Za-z0-9_]{8,}|xox[abprs]-[A-Za-z0-9-]{8,}|"
+    r"\bsk-[A-Za-z0-9_-]{8,}\b|"
+    r"\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b"
+)
 _FILE_LINE_CITATION_RE = re.compile(
     r"`(?P<path>(?!https?://)[^`\n]+?):(?P<line>\d+(?:-\d+)?)`"
 )
@@ -85,6 +110,129 @@ def _audit_evidence_read_paths(content: str) -> set[str]:
     }
 
 
+@dataclass(frozen=True)
+class EvidenceCommand:
+    command: str
+    cwd: str
+    exit_code: int
+    output_summary: str
+
+    def to_record(self) -> dict[str, object]:
+        return {
+            "command": self.command,
+            "cwd": self.cwd,
+            "exitCode": self.exit_code,
+            "outputSummary": self.output_summary,
+        }
+
+
+def _contains_sensitive_material(value: object) -> bool:
+    if isinstance(value, Mapping):
+        return any(
+            (
+                _SENSITIVE_KEY_RE.search(str(key)) is not None
+                and nested not in (None, "", False)
+            )
+            or _contains_sensitive_material(nested)
+            for key, nested in value.items()
+        )
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
+        return any(_contains_sensitive_material(item) for item in value)
+    if not isinstance(value, str):
+        return False
+    return (
+        _SENSITIVE_TEXT_RE.search(value) is not None
+        or _KNOWN_SECRET_RE.search(value) is not None
+    )
+
+
+def _evidence_command_contract_failures(
+    payload: Mapping[str, object], row_number: int
+) -> list[str]:
+    failures: list[str] = []
+    missing = [key for key in _EVIDENCE_COMMAND_FIELDS if key not in payload]
+    unexpected = sorted(set(payload) - set(_EVIDENCE_COMMAND_FIELDS))
+    if missing:
+        failures.append(
+            f"Evidence command row {row_number} is missing {', '.join(missing)}"
+        )
+    if unexpected:
+        failures.append(
+            f"Evidence command row {row_number} has unexpected "
+            f"{', '.join(unexpected)}"
+        )
+    for field_name in _EVIDENCE_COMMAND_STRING_FIELDS:
+        if field_name in payload and not isinstance(payload[field_name], str):
+            failures.append(
+                f"Evidence command row {row_number} {field_name} must be a string"
+            )
+    if "exitCode" in payload and type(payload["exitCode"]) is not int:
+        failures.append(
+            f"Evidence command row {row_number} exitCode must be an integer"
+        )
+    return failures
+
+
+def _evidence_command_from_payload(
+    payload: Mapping[str, object], sensitive: bool
+) -> EvidenceCommand:
+    if sensitive:
+        return EvidenceCommand(
+            command="[redacted: potential secret]",
+            cwd="[redacted: potential secret]",
+            exit_code=payload["exitCode"],
+            output_summary="omitted because potential secret material was detected",
+        )
+    return EvidenceCommand(
+        command=payload["command"],
+        cwd=payload["cwd"],
+        exit_code=payload["exitCode"],
+        output_summary=payload["outputSummary"],
+    )
+
+
+def parse_evidence_commands(
+    content: str,
+) -> tuple[tuple[EvidenceCommand, ...], tuple[str, ...]]:
+    commands: list[EvidenceCommand] = []
+    failures: list[str] = []
+    for row_number, match in enumerate(
+        _EVIDENCE_COMMAND_RE.finditer(content), start=1
+    ):
+        try:
+            payload = json.loads(match.group("payload"))
+        except json.JSONDecodeError:
+            failures.append(f"Evidence command row {row_number} is not valid JSON")
+            continue
+        if not isinstance(payload, Mapping):
+            failures.append(
+                f"Evidence command row {row_number} must be a JSON object"
+            )
+            continue
+        sensitive = _contains_sensitive_material(payload)
+        if sensitive:
+            failures.append(
+                f"Evidence command row {row_number} contains sensitive material"
+            )
+        contract_failures = _evidence_command_contract_failures(payload, row_number)
+        failures.extend(contract_failures)
+        if contract_failures:
+            continue
+        commands.append(_evidence_command_from_payload(payload, sensitive))
+    return tuple(commands), tuple(failures)
+
+
+def read_evidence_commands(
+    audit_path: Path,
+) -> tuple[tuple[EvidenceCommand, ...], tuple[str, ...]]:
+    try:
+        return parse_evidence_commands(audit_path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        return (), (
+            f"worker audit sidecar unreadable: {audit_path.name} ({exc})",
+        )
+
+
 def _worker_prompt_path(
     run_dir: Path,
     worker_role: str,
@@ -276,6 +424,8 @@ def check_worker_results_audit(
             )
             continue
 
+        _, command_failures = read_evidence_commands(audit_path)
+        failures.extend(command_failures)
         failures.extend(_evidence_read_ledger_failures(
             run_dir=run_dir,
             worker_role=worker_role,

package/runtime/schemas/final-report-v2.0.schema.json

@@ -171,6 +171,12 @@
         }
       }
     },
+    "agentActivity": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/AgentActivityRow"
+      }
+    },
     "verificationScope": {
       "enum": [
         "whole-task",
@@ -2587,6 +2593,103 @@
     }
   ],
   "$defs": {
+    "ActivityCommand": {
+      "type": "object",
+      "required": [
+        "command",
+        "cwd",
+        "exitCode",
+        "outputSummary"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "command": {
+          "type": "string"
+        },
+        "cwd": {
+          "type": "string"
+        },
+        "exitCode": {
+          "type": "integer"
+        },
+        "outputSummary": {
+          "type": "string"
+        }
+      }
+    },
+    "AgentActivityRow": {
+      "type": "object",
+      "required": [
+        "activityId",
+        "kind",
+        "agent",
+        "summary",
+        "planItemIds",
+        "resultPath",
+        "commands",
+        "evidenceRefs",
+        "outcome"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "activityId": {
+          "type": "string",
+          "pattern": "^A-\\d{3,}$"
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "worker-dispatched",
+            "worker-completed",
+            "verification-round-completed",
+            "self-fix-applied",
+            "user-decision-required",
+            "user-decision-evaluated"
+          ]
+        },
+        "agent": {
+          "type": "string",
+          "minLength": 1
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "planItemIds": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "resultPath": {
+          "type": "string"
+        },
+        "commands": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ActivityCommand"
+          }
+        },
+        "evidenceRefs": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "outcome": {
+          "type": "string",
+          "enum": [
+            "pending",
+            "completed",
+            "failed",
+            "blocked",
+            "resolved"
+          ]
+        }
+      }
+    },
     "TaskType": {
       "enum": [
         "requirements-discovery",
@@ -3553,6 +3656,86 @@
         "deferred-no-interactive-session"
       ]
     },
+    "ApprovalDisposition": {
+      "enum": [
+        "select",
+        "accept-risk",
+        "request-revision",
+        "reject"
+      ]
+    },
+    "ApprovalResolution": {
+      "type": "object",
+      "required": [
+        "disposition",
+        "userText",
+        "checkRefs"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "disposition": {
+          "$ref": "#/$defs/ApprovalDisposition"
+        },
+        "userText": {
+          "type": "string",
+          "minLength": 1
+        },
+        "checkRefs": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "^A-\\d{3,}$"
+          }
+        }
+      }
+    },
+    "ApprovalContext": {
+      "type": "object",
+      "required": [
+        "classification",
+        "planItemIds",
+        "activityIds",
+        "unblockCondition",
+        "recommendedDisposition"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "classification": {
+          "enum": [
+            "user-decision",
+            "noncritical-dissent",
+            "correctness-critical"
+          ]
+        },
+        "planItemIds": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "^P-[A-Za-z]+-.+"
+          }
+        },
+        "activityIds": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "^A-\\d{3,}$"
+          }
+        },
+        "unblockCondition": {
+          "type": "string",
+          "minLength": 1
+        },
+        "recommendedDisposition": {
+          "$ref": "#/$defs/ApprovalDisposition"
+        },
+        "resolution": {
+          "$ref": "#/$defs/ApprovalResolution"
+        }
+      }
+    },
     "ClarificationOption": {
       "type": "object",
       "required": [
@@ -3593,6 +3776,9 @@
         "directionChange": {
           "type": "string",
           "minLength": 1
+        },
+        "disposition": {
+          "$ref": "#/$defs/ApprovalDisposition"
         }
       }
     },
@@ -8421,6 +8607,9 @@
           "items": {
             "$ref": "#/$defs/ClarificationOption"
           }
+        },
+        "approvalContext": {
+          "$ref": "#/$defs/ApprovalContext"
         }
       }
     },

package/runtime/skills/okstra-user-response/SKILL.md

@@ -73,7 +73,7 @@ okstra user-response show --report <reportPath>
 
 Returns `{reportPath, rows: [{id, kind, blocks, status, statement, expectedForm, options, contextRefs, resolvedRefs}]}`.
 
-Each entry of `options[]` is `{role, answer, rationale, scopeImpact, addedWork, directionChange}`. `role` is `recommended` for exactly one entry and `alternative` for the rest; `scopeImpact` is a token list drawn from `in-repo` / `cross-repo` / `new-schema` / `deferrable`; `addedWork` and `directionChange` are one sentence each. A schema-v1 report has nowhere to record impact, so those three arrive empty — the CLI reconstructs only the answers from the report's `Expected form` cell.
+Each entry of `options[]` is `{role, answer, rationale, scopeImpact, addedWork, directionChange, disposition}`. `role` is `recommended` for exactly one entry and `alternative` for the rest; `scopeImpact` is a token list drawn from `in-repo` / `cross-repo` / `new-schema` / `deferrable`; `addedWork` and `directionChange` are one sentence each. Activity-contract v1 approval options also carry the gate action in `disposition`. A legacy schema-v1 report has nowhere to record impact or a gate action, so those fields arrive empty — the CLI reconstructs only the answers from the report's `Expected form` cell.
 
 `resolvedRefs` is `[{ref, definition}]` — the CLI has already looked up what each internal token (`RB-002`, `FU-001`, `§4.7`, …) means in the report body; `definition` is `null` only when the report text alone could not resolve it (e.g. a `path:line` pointer).
 
@@ -127,7 +127,7 @@ Record one entry — `{id, kind, value, rationale?, disposition}`, `kind` copied
 
 | The user picks | `value` | `disposition` |
 |---|---|---|
-| One of the `options[]` entries | that option's `answer` text, not its short label | `answer` |
+| One of the `options[]` entries | that option's `answer` text, not its short label | that option's `disposition` (`answer` only when absent on a legacy option) |
 | `Enter directly` → their own answer | the user's utterance verbatim (rationale into `rationale`) | `answer` |
 | Free text asking for the item to be re-asked | what the user wants re-asked, verbatim (empty → the raw statement) | `reframe` |
 

package/runtime/templates/reports/final-report-v2.template.md

@@ -110,6 +110,14 @@ schema-version: {{ schemaVersion | yaml_scalar }}
 {{ md_rest(aiTaskProperty, 3) }}
 {% endif %}
 
+{% if md_has("agentActivity") %}
+## {{ t("agentActivity.heading") }}
+
+{{ t("agentActivity.intro") }}
+
+{{ md("agentActivity", 3) }}
+{% endif %}
+
 ## Cross Verification Audit
 
 {{ md("crossVerification", 3) }}