okstra 0.177.1 → 0.178.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.177.1",
+  "version": "0.178.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.177.1",
-  "builtAt": "2026-08-18T18:45:29.329Z",
+  "package": "0.178.0",
+  "builtAt": "2026-08-18T18:51:00.094Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -47,7 +47,7 @@ Read-side inspection (`/okstra-inspect`) and scheduling (`/okstra-schedule-gen`)
 - The `leader` owns orchestration, convergence supervision, and final-report review/approval. It does not author the final-report file when `Report writer worker` is in the roster. `lead` is a compatibility alias for `leader` and must not be written on new artifacts.
 - Dispatch consumes stored role executions, not provider-named worker IDs. Canonical roles are `leader`, `analyser`, `critic`, `designer`, `planner`, `implementer`, `verifier`, `report-writer`, and `translator`. `executor` is a compatibility alias for `implementer`.
 - Pane titles and operational rows use the stored `executionLabel`. Do not rebuild that label from a provider name or model string.
-- `report-writer`, when in the roster, is the **author** of the final-report file. Lead reviews the draft and may request a revision via a follow-up dispatch, but MUST NOT write the report itself as a "shortcut". The only legal lead-authored fallback is when a Report writer worker dispatch was actually attempted and recorded a terminal status of `error`/`timeout`/`not-run` with an explicit reason in team-state — see [report-writer](./report-writer.md) "Lead-authored fallback".
+- `report-writer`, when in the roster, is the **author** of the final-report file. Lead reviews the draft and may request a revision via a follow-up dispatch, but MUST NOT write the report itself as a "shortcut". The only legal lead-authored fallback needs two things together: a Report writer worker dispatch that was actually attempted and recorded a terminal status of `error`/`timeout`/`not-run` with an explicit reason in team-state, **and** the user's permission recorded as a `## REPORT AUTHORING` block in this run's `user-responses/` sidecar. The failure is what lets you ask; only the user can answer. Record both in `header.leadAuthoredFallback` so the report itself carries the fact — see [report-writer](./report-writer.md) "Lead-authored fallback".
 - "Session resume", "team is no longer alive", and similar are NOT valid reasons to skip Report writer worker dispatch — see [report-writer](./report-writer.md) "Resume-safe dispatch".
 - A shell command the lead runs must not be able to ask a question. The lead's shell is the user's own, where `cp`, `mv`, and `rm` are commonly aliased to their `-i` form; the confirmation that alias raises has nobody to answer it, so the call hangs until it is killed — observed as a `cp` over an existing state file stalling a whole self-fix round. Invoke these as `command cp` / `command mv` / `command rm`, which skips alias expansion and leaves the tool's own behaviour untouched. `-f` is not a substitute: it changes what the tool does on failure (`rm -f` reports success on a path that never existed).
 - If the brief is incomplete, continue with explicit uncertainty markers rather than fabricating confidence.

package/runtime/prompts/lead/report-writer.md

@@ -81,9 +81,13 @@ Except for `release-handoff` (which is single-lead by design and never dispatche
 1. A Report writer worker dispatch was actually attempted through `dispatch_worker`.
 2. The attempt recorded a terminal status of `error`, `timeout`, or `not-run` with a concrete reason (tool error message, timeout duration, or external blocker).
 3. The reason is logged via `okstra error-log append-observed --error-type cli-failure ...` (or `tool-failure` if the failure was internal).
+4. **The user permitted it.** Ask at a gate, and have the answer written to this run's `user-responses/` sidecar as a `## REPORT AUTHORING` block with `- Status: approved` (`okstra user-response write --report <data.json> --answers '[]' --report-authoring '{"status":"approved","reason":"<the user's words>"}'`). A failed dispatch is your cue to ask, not your permission — a lead that dispatches once, watches it fail, and proceeds has still decided alone. You cannot write this block for yourself; it is the user's answer, in the user's file.
+5. **Record it in the report.** Set `header.leadAuthoredFallback` with `dispatchFailureReason` quoted verbatim from the failed dispatch row and `approvalSidecar` set to that sidecar's project-relative path. The approval passes the gate; it does not retire it. This block renders under `Report Author`, so someone reading the report months later sees that this run left the report-writer path and why, without having to find the sidecar.
 
 Speculative reasons such as "session resume constraint", "runtime state is unavailable", or "lead can do it faster" are NOT valid.
 
+**Enforced:** `validators/validate-run.py` `_validate_lead_authored_report` checks all of it — the terminal failure status, its reason, the approving sidecar block, and the `header.leadAuthoredFallback` record whose reason must match the dispatch row. `release-handoff` is exempt because it never dispatches a report writer.
+
 
 ## Phase 6 → Phase 7 execution sequence (BLOCKING order)
 
@@ -185,7 +189,7 @@ Read the exact permitted values for `header.reportOwner` and `header.reportAutho
 - Report Owner: `<exact schema header.reportOwner compatibility value>`
 - Report Author: `<exact schema header.reportAuthor compatibility value for the actual authorship path>`
 - Lead model: `<lead-model>`
-- Preparation Method: Final report authored by Report writer worker (or lead-authored fallback — record the documented dispatch failure reason here when applicable)
+- Preparation Method: Final report authored by Report writer worker (or lead-authored fallback — record the documented dispatch failure reason here when applicable; the machine-readable record is `header.leadAuthoredFallback`, which is what the validator and the rendered report both read)
 ```
 
 ### Agent-Specific Execution Status Table

package/runtime/python/okstra_ctl/report_views.py

@@ -1123,6 +1123,19 @@ _ANALYSIS_REVIEW_STATUSES = frozenset({
 })
 
 PLAN_DECISION_APPROVED = "approved"
+@dataclass(frozen=True)
+class UserReportAuthoring:
+    """사용자가 리드의 최종 리포트 직접 저작을 허가했는지에 대한 답.
+
+    승인이어도 ``reason`` 이 필수다 — 리포트 헤더가 이 사유를 그대로 실어
+    나중에 읽는 사람이 이 run 이 왜 report-writer 경로를 벗어났는지 본다."""
+    status: str
+    reason: str = ""
+
+
+REPORT_AUTHORING_APPROVED = "approved"
+_REPORT_AUTHORING_STATUSES = frozenset({REPORT_AUTHORING_APPROVED, "denied"})
+
 _PLAN_DECISION_STATUSES = frozenset({
     PLAN_DECISION_APPROVED,
     "revision-requested",
@@ -1208,6 +1221,25 @@ def _serialize_plan_decision(decision: UserPlanDecision) -> str:
     return chunk
 
 
+def _serialize_report_authoring(decision: UserReportAuthoring) -> str:
+    """The user's answer on letting the lead author the final report itself.
+
+    Same shape as PLAN DECISION because it is the same kind of fact: a decision
+    only the user may make, written into the sidecar the user owns. A reason is
+    required even on approval — the report carries it forward, so a later reader
+    sees why this run left the report-writer path.
+    """
+    if decision.status not in _REPORT_AUTHORING_STATUSES:
+        raise ValueError(f"invalid REPORT AUTHORING status: {decision.status}")
+    if not decision.reason.strip():
+        raise ValueError("REPORT AUTHORING requires a Reason")
+    return (
+        "\n## REPORT AUTHORING\n"
+        f"- Status: {decision.status}\n"
+        f"{_quoted_sidecar_field('Reason', decision.reason)}"
+    )
+
+
 def _serialize_direction_selection(selection: UserDirectionSelection) -> str:
     option_id, option_name = normalize_direction_selection_identity(
         selection.option_id, selection.option_name
@@ -1233,6 +1265,7 @@ def serialize_user_response(
     plan_decision: UserPlanDecision | None = None,
     analysis_review: UserResponseAnalysisReview | None = None,
     direction_selection: UserDirectionSelection | None = None,
+    report_authoring: UserReportAuthoring | None = None,
 ) -> str:
     """Return the canonical markdown text the HTML 'Export user
     response' button must produce. Used by validators to confirm that
@@ -1285,6 +1318,8 @@ def serialize_user_response(
         body_chunks.append(_serialize_analysis_review(analysis_review))
     if direction_selection is not None:
         body_chunks.append(_serialize_direction_selection(direction_selection))
+    if report_authoring is not None:
+        body_chunks.append(_serialize_report_authoring(report_authoring))
     return head + "".join(body_chunks)
 
 

package/runtime/python/okstra_ctl/user_response.py

@@ -21,7 +21,8 @@ from typing import Optional
 from okstra_ctl.report_views import (
     PLAN_DECISION_APPROVED,
     normalize_direction_selection_identity,
-    serialize_user_response, UserResponseEntry, UserPlanDecision, infer_run_meta,
+    serialize_user_response, UserResponseEntry, UserPlanDecision,
+    UserReportAuthoring, infer_run_meta,
     parse_expected_form_options,
 )
 from okstra_ctl.report_view_artifacts import user_responses_dir_for_report
@@ -669,7 +670,8 @@ def show_open_rows(report_path: Path) -> dict:
 
 def write_sidecar(report_path: Path, answers: list[dict],
                   plan_decision: Optional[dict], created_at: str,
-                  task_key: str = "") -> Path:
+                  task_key: str = "",
+                  report_authoring: Optional[dict] = None) -> Path:
     run_meta = infer_run_meta(report_path, task_key=task_key or None)
     out_dir = user_responses_dir_for_report(report_path)
     out_dir.mkdir(parents=True, exist_ok=True)
@@ -690,9 +692,15 @@ def write_sidecar(report_path: Path, answers: list[dict],
             status=plan_decision["status"],
             implementation_option=plan_decision.get("implementationOption", ""),
             reason=plan_decision.get("reason", ""))
+    authoring = None
+    if report_authoring and report_authoring.get("status"):
+        authoring = UserReportAuthoring(
+            status=report_authoring["status"],
+            reason=report_authoring.get("reason", ""))
     sidecar.write_text(
         serialize_user_response(run_meta=run_meta, entries=list(merged.values()),
-                                created_at=created_at, plan_decision=decision),
+                                created_at=created_at, plan_decision=decision,
+                                report_authoring=authoring),
         encoding="utf-8")
     return sidecar
 
@@ -715,6 +723,11 @@ def main(argv: Optional[list[str]] = None) -> int:
     pw.add_argument(
         "--plan-decision", default="",
         help='JSON plan decision, e.g. {"status":"rejected","reason":"..."}')
+    pw.add_argument(
+        "--report-authoring", default="",
+        help='JSON report-authoring permission, e.g. '
+             '{"status":"approved","reason":"report-writer failed twice"}. '
+             'Only the user may grant this; the lead cannot write it for itself.')
     pw.add_argument("--task-key", default="", help="task-key from list/show context")
 
     ns = parser.parse_args(argv)
@@ -728,9 +741,12 @@ def main(argv: Optional[list[str]] = None) -> int:
     if ns.cmd == "write":
         answers = json.loads(ns.answers)
         decision = json.loads(ns.plan_decision) if ns.plan_decision else None
+        authoring = (
+            json.loads(ns.report_authoring) if ns.report_authoring else None
+        )
         created_at = dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
         p = write_sidecar(Path(ns.report), answers, decision, created_at,
-                          task_key=ns.task_key)
+                          task_key=ns.task_key, report_authoring=authoring)
         json.dump({"sidecar": str(p)}, sys.stdout, ensure_ascii=False)
         return 0
     return 1

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

@@ -191,6 +191,27 @@
           ],
           "description": "Lead-authored fallback is only valid for release-handoff or recorded report-writer dispatch failure."
         },
+        "leadAuthoredFallback": {
+          "type": "object",
+          "description": "Why this run took the lead-authored fallback and who permitted it. Present exactly when reportAuthor is `Okstra lead` on a task type other than release-handoff. The approval passes the gate but does not retire it: this block is what a later reader sees, so the run does not read as a normal report-writer run once the sidecar is out of view.",
+          "required": [
+            "dispatchFailureReason",
+            "approvalSidecar"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "dispatchFailureReason": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The reason recorded on the failed report-writer dispatch row, verbatim."
+            },
+            "approvalSidecar": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Project-relative path of the user-responses sidecar carrying the approving `## REPORT AUTHORING` block."
+            }
+          }
+        },
         "leadModel": {
           "type": "string",
           "minLength": 1

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

@@ -34,7 +34,8 @@ schema-version: {{ schemaVersion | yaml_scalar }}
 - Task Type: `{{ header.taskType }}`
 - Report Owner: `{{ header.reportOwner }}`
 - Report Author: `{{ header.reportAuthor }}`
-- Lead Model: `{{ header.leadModel | model_detail }}`
+{% if header.leadAuthoredFallback %}- Lead-authored fallback: report-writer dispatch failed — `{{ header.leadAuthoredFallback.dispatchFailureReason }}`; permitted by the user in `{{ header.leadAuthoredFallback.approvalSidecar }}`
+{% endif %}- Lead Model: `{{ header.leadModel | model_detail }}`
 - Okstra Version: `{{ header.okstraVersion }}`
 
 ## AI Handoff Summary

package/runtime/validators/validate-run.py

@@ -3499,6 +3499,7 @@ def validate_final_report_data(
         )
     elif task_type == "implementation":
         _validate_stage_carry_sidecar_exists(data, report_path, failures)
+    _validate_lead_authored_report(data, report_path, failures)
     if task_type == "error-analysis":
         _validate_error_analysis_consistency(data, failures)
     elif task_type == "final-verification":
@@ -6369,6 +6370,138 @@ def _validate_verifier_fail_blocks_verdict(data: dict, failures: list[str]) -> N
         )
 
 
+
+_LEAD_AUTHORED = "Okstra lead"
+_REPORT_AUTHORING_HEADING_RE = re.compile(r"^## REPORT AUTHORING\s*$", re.MULTILINE)
+_REPORT_AUTHORING_APPROVED = "approved"
+# `report-writer.md` "Lead-authored fallback": the attempt must have reached one
+# of these with a concrete reason. `completed` means the worker produced the
+# report, so the lead had nothing to fall back from.
+_DISPATCH_FAILURE_STATUSES = {"error", "timeout", "not-run"}
+
+
+def _report_authoring_approval(report_path: Path) -> str:
+    """The user's recorded answer on letting the lead author this report.
+
+    Read from the run's `user-responses/` sidecars, the same channel the
+    clarification and plan-decision answers already use. The file is written by
+    the user through `okstra user-response write`, which is the point: an
+    approval the lead could author itself would be the self-report this gate
+    exists to remove.
+    """
+    sidecar_dir = report_path.parent.parent / "user-responses"
+    if not sidecar_dir.is_dir():
+        return ""
+    for sidecar in sorted(sidecar_dir.glob("*.md")):
+        try:
+            text = sidecar.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        match = _REPORT_AUTHORING_HEADING_RE.search(text)
+        if not match:
+            continue
+        block = text[match.end():]
+        next_heading = re.search(r"^## ", block, re.MULTILINE)
+        if next_heading:
+            block = block[: next_heading.start()]
+        status = re.search(r"^-\s*Status:\s*(.+?)\s*$", block, re.MULTILINE)
+        if status:
+            return status.group(1).strip()
+    return ""
+
+
+def _validate_lead_authored_report(
+    data: dict,
+    report_path: Path,
+    failures: list[str],
+) -> None:
+    """A lead-authored final report needs a failed dispatch AND a user approval.
+
+    `header.reportAuthor` renders in the report but nothing read it, so a lead
+    could name itself the author with no dispatch behind it. The contract has
+    always required a real attempt that recorded a terminal failure with a
+    reason; this adds the second door, because a lead that dispatches once,
+    lets it fail, and proceeds has still decided alone. Neither door retires
+    the other: an approval does not excuse a missing attempt, and an attempt
+    that failed is the cue to ask, not the permission.
+
+    The record is not consumed by passing. The failure reason and the approval
+    both stay on disk, and `header.reportAuthor` stays `Okstra lead` in the
+    rendered report, so a later reader sees that this run took the fallback and
+    why.
+    """
+    header = data.get("header")
+    if not isinstance(header, Mapping):
+        return
+    if str(header.get("reportAuthor") or "").strip() != _LEAD_AUTHORED:
+        return
+    # release-handoff has no worker roster at all: it is single-lead by design,
+    # so there is no dispatch to fail and nothing for the user to permit.
+    if str(header.get("taskType") or "").strip() == "release-handoff":
+        return
+
+    team_state = data.get("teamState")
+    dispatches = (
+        team_state.get("workerDispatches") if isinstance(team_state, Mapping) else None
+    )
+    attempts = [
+        row
+        for row in (dispatches if isinstance(dispatches, list) else [])
+        if isinstance(row, Mapping)
+        and str(row.get("workerId") or "").strip() == "report-writer"
+    ]
+    failed = [
+        row
+        for row in attempts
+        if str(row.get("status") or "").strip() in _DISPATCH_FAILURE_STATUSES
+    ]
+    if not failed:
+        failures.append(
+            "final-report data.json: `header.reportAuthor` is `Okstra lead` but "
+            "no report-writer dispatch recorded a terminal failure "
+            f"({', '.join(sorted(_DISPATCH_FAILURE_STATUSES))}) in team-state. "
+            "The lead-authored fallback is reachable only from an attempt that "
+            "actually failed (prompts/lead/report-writer.md "
+            "'Lead-authored fallback')"
+        )
+    elif not any(str(row.get("reason") or "").strip() for row in failed):
+        failures.append(
+            "final-report data.json: the report-writer dispatch failed but "
+            "recorded no reason, so the lead-authored fallback rests on an "
+            "unexplained failure. Record the tool error, the timeout, or the "
+            "external blocker on the dispatch row"
+        )
+
+    fallback = header.get("leadAuthoredFallback")
+    if not isinstance(fallback, Mapping):
+        failures.append(
+            "final-report data.json: `header.reportAuthor` is `Okstra lead` but "
+            "`header.leadAuthoredFallback` is absent. The approval passes the "
+            "gate; it does not erase it — the failure reason and the approving "
+            "sidecar belong in the report a human reads, not only in the "
+            "sidecars they would have to go find"
+        )
+    else:
+        recorded = str(fallback.get("dispatchFailureReason") or "").strip()
+        reasons = {str(row.get("reason") or "").strip() for row in failed}
+        if recorded and reasons and recorded not in reasons:
+            failures.append(
+                "final-report data.json: "
+                "`header.leadAuthoredFallback.dispatchFailureReason` does not "
+                "match any reason recorded on a failed report-writer dispatch. "
+                "Quote the dispatch row verbatim rather than restating it"
+            )
+
+    approval = _report_authoring_approval(report_path)
+    if approval != _REPORT_AUTHORING_APPROVED:
+        found = f"`{approval}`" if approval else "no `## REPORT AUTHORING` block"
+        failures.append(
+            "final-report data.json: `header.reportAuthor` is `Okstra lead` but "
+            f"the run's `user-responses/` sidecars carry {found}. Only the user "
+            "may permit the lead to author the report; ask at a gate and have "
+            "the answer written through `okstra user-response write`"
+        )
+
 def _validate_stage_carry_sidecar_exists(
     data: dict,
     report_path: Path,