okstra 0.199.1 → 0.199.3

package/runtime/python/okstra_ctl/report_synthesis_packet.py

@@ -246,6 +246,13 @@ class ReportSynthesisPacket:
             "that exact order.",
             "`endStateCoverage` must contain exactly one row per original "
             "requirement id; an `addressed` row names its `coveredBy` anchor.",
+            "Coverage references use existing identifiers: `stageRefs` contains stage numbers, "
+            "`stepRefs` uses `<stage>.<step>` (for example `1.2`), `validationRefs` uses "
+            "validation checklist ids, and `fileRefs` uses exact changed file paths without annotations. "
+            "Map QA script changes to their requirements too. A future follow-up is not a stage or validation id.",
+            "Derive `coverageSummary` from the coverage rows; do not declare exact 100% "
+            "or `plan-ready` while requirements are uncovered or file changes are unmapped. "
+            "Preserve recorded user decisions when describing deferred work.",
         ]
 
     def to_dict(self) -> dict[str, Any]:

package/runtime/python/okstra_ctl/run.py

@@ -394,6 +394,16 @@ def _validate_approved_plan_conformance(path: Path) -> None:
     if loaded is None:
         return
     data_path, data = loaded
+    from .implementation_direction import stage_validation_executability_errors
+
+    command_errors = stage_validation_executability_errors(
+        data.get("implementationPlanning") or {}
+    )
+    if command_errors:
+        raise PrepareError(
+            f"approved plan command preflight failed: {data_path}\n"
+            + "\n".join(command_errors)
+        )
     bad = malformed_conformance_stages(data)
     if not bad:
         return

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -391,6 +391,19 @@ def complete_reverify_instruction(
         if not body.lstrip().startswith(("## ", "**")):
             body = "## Instructions\n\n" + body
         body = "\n".join(prefix) + "\n\n" + body
+    if task_type == "implementation-planning":
+        # 저장된 금지 목록은 감사 대조용으로 유지하되 폐기된 작성 의무를 정정한다.
+        body = body.rstrip() + (
+            "\n\n## Planning conformance ownership\n\n"
+            "Planning declares conformance commands and required dependencies; "
+            "implementation writes the QA scripts, manifest, and tsconfig. "
+            "Do not create those files during planning. Their absence before "
+            "implementation is not a planning defect by itself. This phase "
+            "ownership supersedes any legacy requirement in the frozen Forbidden "
+            "actions block saying this phase MUST write those artifacts. "
+            "Verify that the plan assigns their creation to implementation and "
+            "provides executable commands and required dependencies.\n"
+        )
     if _OUTPUT_CONTRACT_HEADING not in body:
         body = body.rstrip() + "\n\n" + output_contract.strip() + "\n"
     errors = _validate_output_contract_block(body)

package/runtime/python/okstra_ctl/worker_prompt_policy.py

@@ -121,6 +121,16 @@ def is_plan_verify_dispatch_kind(dispatch_kind: str) -> bool:
     return _numbered_round(dispatch_kind, PLAN_VERIFY_DISPATCH_KIND_PREFIX) is not None
 
 
+def is_plan_critic_verification(
+    *, task_type: str, assignment_ref: str, dispatch_kind: str,
+) -> bool:
+    return (
+        task_type == "implementation-planning"
+        and assignment_ref == "critic/scope"
+        and is_plan_verify_dispatch_kind(dispatch_kind)
+    )
+
+
 def verification_dispatch_round(dispatch_kind: str) -> int | None:
     """검증 kind 가 적는 라운드 번호. 번호 없는 kind(`critic-verify`)는 1,
     검증 kind 가 아니거나 번호가 깨졌으면 None.

package/runtime/skills/okstra-inspect/SKILL.md

@@ -28,19 +28,21 @@ Single read-side entry point for okstra runtime inspection plus the one status m
 
 ## Step 0: Preflight (shared)
 
+Resolve `<host-runtime>` from the launcher's `OKSTRA_RUNTIME_HOST` when present; otherwise use the registered host ID declared by the current harness (`codex` in Codex, `claude-code` in Claude Code). This follows `okstra-run`'s host selection rule. Do not infer the host from worker models, installed executables, or `PATH`. If neither source identifies the host, report that it is unknown instead of substituting Claude Code. Keep the same resolved host when retrying against another project directory.
+
 <!-- BEGIN FRAGMENT: bash-invocation-rule -->
 Run one Bash tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match):
 <!-- END FRAGMENT: bash-invocation-rule -->
 
 ```bash
-okstra preflight --runtime claude-code
+okstra preflight --runtime <host-runtime>
 ```
 
 The project check only sees the cwd of the Bash call. When the user is asking about a project that is **not** the cwd (a sibling repo, a monorepo subdir, or a project named explicitly in the request), the bare form can report `Okstra preflight: failed` — a false negative, not a missing setup; do not hard-stop on it.
 
 Branch on the fixed first line:
 - `Okstra preflight: ready` → carry `Project root` as a literal string; it is the base for every sub-command step below.
-- `Okstra preflight: failed` → before concluding "no setup", ask whether the user pointed at a specific project directory. If they did, re-run targeting it: `okstra preflight --runtime claude-code --cwd <that-dir>` (`--cwd` is the sanctioned way to target a project — a leading `cd` would break the permission match). Only if this also fails do you show `Reason` and `Recovery`, then stop.
+- `Okstra preflight: failed` → before concluding "no setup", ask whether the user pointed at a specific project directory. If they did, re-run targeting it: `okstra preflight --runtime <host-runtime> --cwd <that-dir>` (`--cwd` is the sanctioned way to target a project — a leading `cd` would break the permission match). Only if this also fails do you show `Reason` and `Recovery`, then stop.
 
 <!-- BEGIN FRAGMENT: preflight-outdated-cli -->
 If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).

package/runtime/skills/okstra-run/SKILL.md

@@ -475,4 +475,4 @@ Do not read the wizard state file directly. `okstra wizard outcome` exposes any
 - Echo each captured answer (`result.echo`) on one short line so the user sees what was registered.
 - Name every file you show the user as a markdown link — `[<what it is>](<path>)`, with the path inside the parentheses. That is the only form the host renders as clickable; a path in backticks is text the user has to copy out. The `report-finalize` result's `reportPaths.markdown` carries the run's report, report record, and team state already in that form. Commands stay in backticks — a link is for a file, not for something to run.
 - Never invent identity; if a `text` prompt returns an empty answer where the wizard rejects it, the user must retry.
-- After Step 6, begin the lead workflow without re-summarizing the skill itself. For a single run, the end of Step 6 is the end of the run — but in an unattended chain where `orchestration.chainStages` has 2+ elements, repeat Step 6 per stage until Step 7's queue is empty (or it stops at a "not ready" / exception gate), then finish. When the lead (or this skill, after the lead returns) reports the run over, close with the user's next action — one command they can run now. A prohibition is not a next action. Take the pointer from the `report-finalize` result's top-level `nextRecommendedPhase` (`phase`, `status`, `rationale`; also on stderr as `next phase status:` / `next phase:` / `next phase rationale:`) — do not re-derive it from the report, and treat a `nextRecommendedPhaseError` as "pointer unreadable", said in one line before the `validate-run` branch. The same result also carries `nextCommand` — `{command, note}`, the table below already applied to this run. When `command` is non-empty it is the close; when it is empty the `note` says what to do with the `rationale` instead. After `implementation-planning`, open `blocks: approval` rows → `/okstra-user-response`. A recorded `accept-risk` / `select` / `answer` is not an open blocker. No open approval blocker → `/okstra-run` → `implementation` or `--approve` (do not start another planning run; do not say `/okstra-inspect`). For every other task type, quote the pointer's `rationale` in every branch — that sentence is the report's own reason and it is what the user asked to be analysed. Pointer `status: ready` → `/okstra-run` for that phase; `status: terminal` → say the task is finished, name any follow-up tasks this run registered, and do not say `/okstra-inspect`; `status: blocked` → issue the command the `rationale` calls for (`/okstra-user-response` for the `C-NNN` ids, `/okstra-run` for the phase it names); `validate-run` failed → one-line cause then `/okstra-run`; otherwise `/okstra-inspect status`.
+- After Step 6, begin the lead workflow without re-summarizing the skill itself. For a single run, the end of Step 6 is the end of the run — but in an unattended chain where `orchestration.chainStages` has 2+ elements, repeat Step 6 per stage until Step 7's queue is empty (or it stops at a "not ready" / exception gate), then finish. When `report-finalize` returns `recovery.mode: same-run`, continue the authorized corrections in this run and execute `recovery.resumeCommand` before closeout; preserve approvals and model choices without reopening the wizard. The command and owner issues are supplied by `report_finalize._finalize_recovery`. When the lead (or this skill, after the lead returns) reports a successfully finalized run over, close with the user's next action — one command they can run now. A prohibition is not a next action. Take the pointer from the `report-finalize` result's top-level `nextRecommendedPhase` (`phase`, `status`, `rationale`; also on stderr as `next phase status:` / `next phase:` / `next phase rationale:`) — do not re-derive it from the report, and treat a `nextRecommendedPhaseError` as "pointer unreadable", said in one line before the `validate-run` branch. The same result also carries `nextCommand` — `{command, note}`, the table below already applied to this run. When `command` is non-empty it is the close; when it is empty the `note` says what to do with the `rationale` instead. After `implementation-planning`, open `blocks: approval` rows → `/okstra-user-response`. A recorded `accept-risk` / `select` / `answer` is not an open blocker. No open approval blocker → `/okstra-run` → `implementation` or `--approve` (do not start another planning run; do not say `/okstra-inspect`). For every other task type, quote the pointer's `rationale` in every branch — that sentence is the report's own reason and it is what the user asked to be analysed. Pointer `status: ready` → `/okstra-run` for that phase; `status: terminal` → say the task is finished, name any follow-up tasks this run registered, and do not say `/okstra-inspect`; `status: blocked` → issue the command the `rationale` calls for (`/okstra-user-response` for the `C-NNN` ids, `/okstra-run` for the phase it names); `validate-run` failed with `recovery.mode: phase-reentry` → name the cause and use `nextCommand` for the recorded earlier phase; otherwise `/okstra-inspect status`.

package/runtime/validators/forbidden_actions.py

@@ -108,11 +108,14 @@ def verifier_mutation_hits(command_log: str) -> list[tuple[str, str]]:
     로그는 자유 문자열이라 줄 단위로 본다 — 어느 명령이 문제인지 그대로 보고해야
     작성자가 고칠 자리를 안다. heredoc 본문은 기록되는 데이터이므로 걷어낸다.
     """
+    from okstra_ctl.qa_commands import find_unfrozen_installs
+
     hits: list[tuple[str, str]] = []
     for raw in strip_heredoc_bodies(command_log or "").splitlines():
         line = raw.strip()
         if not line or line.startswith("#"):
             continue
+        hits.extend((label, line) for label in find_unfrozen_installs(line))
         for label, pattern in (*_VERIFIER_MUTATION, *_VERIFIER_SOURCE_MUTATION):
             if pattern.search(line):
                 hits.append((label, line))

package/runtime/validators/validate-run.py

@@ -902,11 +902,22 @@ def update_workflow_metadata(
         if current_phase:
             phase_states[current_phase] = current_phase_state
         last_completed_phase = workflow.get("lastCompletedPhase", "")
+        recovery = next_phase.project(report_data or {})
+        recovery_phase = recovery["phase"]
+        can_backtrack = (
+            current_phase in PHASE_SEQUENCE
+            and recovery_phase in PHASE_SEQUENCE
+            and PHASE_SEQUENCE.index(recovery_phase)
+            < PHASE_SEQUENCE.index(current_phase)
+        )
         next_recommended_phase = next_phase.make(
+            phase=recovery_phase if can_backtrack else "",
             status=next_phase.STATUS_BLOCKED,
             rationale=_blocked_rationale(
-                current_phase,
-                inherited_pointer["rationale"],
+                recovery_phase if can_backtrack else current_phase,
+                recovery["rationale"]
+                if can_backtrack
+                else inherited_pointer["rationale"],
                 failures,
                 run_manifest_path=str(run_manifest.get("runManifestPath") or ""),
             ),
@@ -2197,6 +2208,12 @@ def _validate_planning_conformance_declared(
     if not isinstance(ip, dict):
         return
     _planning_conformance_declarations(ip.get("stages"), failures)
+    if ip.get("planningContract") != "selected-direction":
+        from okstra_ctl.implementation_direction import (
+            stage_validation_executability_errors,
+        )
+
+        failures.extend(stage_validation_executability_errors(ip))
     for conflict in exempt_stage_surface_conflicts(data, surface_patterns):
         failures.append(
             "conformance gate BLOCKING: stage "
@@ -3688,31 +3705,30 @@ def _single_vote_block_survives(item: dict, kinds: set[str]) -> bool:
 
 
 def _critic_non_error_verdicts(item: dict) -> list[dict]:
-    return [
-        row
-        for row in (item.get("verdicts") or [])
-        if isinstance(row, dict)
-        and is_critic_worker(str(row.get("worker") or ""))
-        and str(row.get("verdict") or "").strip().upper()
-        not in ("", "VERIFICATION-ERROR")
-    ]
+    """현재 기록된 비판 검토자의 최신 유효 판정."""
+    rows = [row for row in item.get("verdicts", []) if isinstance(row, dict)]
+    critic = [row for row in rows
+              if is_critic_worker(row.get("worker", ""))
+              and str(row.get("verdict", "")).upper() in {"AGREE", "SUPPLEMENT", "DISAGREE"}]
+    latest = max((row.get("round", 1) for row in critic), default=0)
+    return [row for row in critic if row.get("round", 1) == latest]
 
 
-def _tie_gate_class(item: dict, agree: list, disagree: list) -> str | None:
-    """분석자 동수면 critic 이 가르고, 없으면 재검증. 동수가 아니면 None."""
-    if not (len(disagree) == len(agree) and disagree):
-        return None
+def _critic_gate_class(item: dict) -> str | None:
+    """비판 검토자의 교정 권한은 분석자의 표수나 동수 여부에 의존하지 않는다."""
     critic = _critic_non_error_verdicts(item)
     if not critic:
-        return "needs-reverify"
-    if any(
-        str(row.get("verdict") or "").strip().upper() == "DISAGREE"
-        and str(row.get("breakageKind") or "").strip().lower()
-        not in _ADVISORY_ONLY_KINDS
-        for row in critic
-    ):
-        return "majority-disagree"
-    return "has-dissent"
+        return None
+    critic_dissent = [row for row in critic if str(row.get("verdict", "")).upper() == "DISAGREE"]
+    if critic_dissent:
+        if str(item.get("id", "")).upper().startswith("P-RB"):
+            return "has-dissent"
+        return "majority-disagree" if any(
+            str(row.get("breakageKind", "")).lower() not in _ADVISORY_ONLY_KINDS
+            for row in critic_dissent
+        ) else "has-dissent"
+    dissent = any(str(row.get("verdict", "")).upper() == "DISAGREE" for row in item.get("verdicts", []))
+    return "has-dissent" if dissent else "full-consensus"
 
 
 def _classify_plan_item_gate(item: dict) -> str:
@@ -3726,6 +3742,9 @@ def _classify_plan_item_gate(item: dict) -> str:
     reproduction. An analyser 1-1 is ``needs-reverify`` until ``critic-worker``
     settles it.
     """
+    corrected = _critic_gate_class(item)
+    if corrected is not None:
+        return corrected
     tokens = [
         (
             str(v.get("verdict") or "").strip().upper(),
@@ -3783,9 +3802,8 @@ def _classify_plan_item_gate(item: dict) -> str:
     # made the gate stricter than a healthy roster would.
     if len(non_error) >= 2 and len(blocking_disagree) > len(agree):
         return "majority-disagree"
-    settled = _tie_gate_class(item, agree, blocking_disagree)
-    if settled is not None and len(non_error) >= 2:
-        return settled
+    if len(blocking_disagree) == len(agree) and len(non_error) >= 2:
+        return "needs-reverify"
     if (
         len(non_error) >= 2
         and blocking_disagree
@@ -9363,13 +9381,66 @@ def _data_schema_failures(data: dict) -> list[str]:
     ]
 
 
+def run_preflight(report_path: Path, run_manifest_path: Path) -> int:
+    """번역·표시·상태 갱신 전에 정본의 구조와 적합성만 검사한다."""
+    try:
+        data = load_json(_data_path_for(report_path))
+        manifest = load_json(run_manifest_path)
+        if not isinstance(data, dict) or not isinstance(manifest, dict):
+            raise TypeError("preflight requires report and run-manifest JSON objects")
+    except (OSError, ValueError, TypeError) as exc:
+        print(json.dumps({"ok": False, "failures": [str(exc)]}))
+        return 2
+    failures = _data_schema_failures(data)
+    task_type = manifest.get("taskType")
+    warnings: list[str] = []
+    if task_type in ("implementation", "final-verification"):
+        project_root = Path(
+            str(manifest.get("projectRoot") or run_manifest_path.parent)
+        )
+        warnings = _validate_conformance(
+            report_path,
+            failures,
+            surface_patterns=_project_surface_patterns(project_root),
+            approved_plan_path=_approved_plan_path_from_run_inputs(
+                run_manifest_path, failures
+            ),
+        )
+    elif task_type == "implementation-planning":
+        from okstra_ctl.report_assembly import selected_direction_plan_errors
+        from okstra_ctl.implementation_direction import (
+            stage_validation_executability_errors,
+        )
+
+        failures.extend(
+            stage_validation_executability_errors(
+                data.get("implementationPlanning") or {}
+            )
+        )
+        failures.extend(selected_direction_plan_errors(
+            data, Path(str(manifest.get("projectRoot") or run_manifest_path.parent)), manifest
+        ))
+        _validate_planning_conformance_declared(report_path, failures)
+    print(
+        json.dumps(
+            {
+                "ok": not failures,
+                "failures": list(dict.fromkeys(failures)),
+                "warnings": warnings,
+            },
+            ensure_ascii=False,
+        )
+    )
+    return 2 if failures else 0
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(
         description="Validate okstra run contract artifacts."
     )
     parser.add_argument(
         "--section",
-        choices=(SECTION_FULL, SECTION_PLAN_BODY),
+        choices=(SECTION_FULL, SECTION_PLAN_BODY, "preflight"),
         default=SECTION_FULL,
         help=(
             "Which contract surface to validate. `full` (default) validates the "
@@ -9415,6 +9486,13 @@ def main() -> int:
     )
     args = parser.parse_args()
 
+    if args.section == "preflight":
+        if not args.report or not args.run_manifest:
+            parser.error("--section preflight requires --report and --run-manifest")
+        return run_preflight(
+            Path(args.report).resolve(), Path(args.run_manifest).resolve()
+        )
+
     if args.section == SECTION_PLAN_BODY:
         if args.narrative and args.state and not args.report:
             return run_plan_body_inputs(

package/runtime/validators/validate_session_conformance.py

@@ -561,6 +561,11 @@ def _progress_line_from_event(event) -> tuple[str, str, str] | None:
         message = details.get("message")
         tail = f" {message}" if isinstance(message, str) and message else ""
         line = f"PROGRESS: {phase}{tail}"
+    worker = details.get("worker")
+    if isinstance(worker, str) and worker.strip():
+        from okstra_ctl.lead_progress import render_progress_line
+
+        line = render_progress_line(phase, [("worker", worker), ("detail", line)])
     return (event.timestamp, phase, line)