okstra 0.163.2 → 0.165.0

package/runtime/python/okstra_ctl/user_response.py

@@ -3,7 +3,7 @@
 The sidecar format is documented in ``templates/reports/user-response.template.md``
 and produced byte-identically by ``report_views.serialize_user_response`` (Python)
 and ``templates/reports/report.js`` (browser). This module owns the read side of
-the ``## APPROVAL`` block used by the implementation wizard and the optional
+the ``## PLAN DECISION`` block used by the implementation wizard and the optional
 ``## ANALYSIS REVIEW`` block used by analysis reruns.
 """
 from __future__ import annotations
@@ -19,7 +19,8 @@ from pathlib import Path
 from typing import Optional
 
 from okstra_ctl.report_views import (
-    serialize_user_response, UserResponseEntry, UserResponseApproval, infer_run_meta,
+    PLAN_DECISION_APPROVED,
+    serialize_user_response, UserResponseEntry, UserPlanDecision, infer_run_meta,
     parse_expected_form_options,
 )
 from okstra_ctl.report_view_artifacts import user_responses_dir_for_report
@@ -32,7 +33,7 @@ from okstra_ctl.clarification_items import (
     _section_1_slice,
 )
 
-_APPROVAL_HEADING_RE = re.compile(r"^## APPROVAL\s*$", re.MULTILINE)
+_PLAN_DECISION_HEADING_RE = re.compile(r"^## PLAN DECISION\s*$", re.MULTILINE)
 _NEXT_RESPONSE_HEADING_RE = re.compile(r"^## ", re.MULTILINE)
 _ANALYSIS_REVIEW_HEADING_RE = re.compile(r"^## ANALYSIS REVIEW\s*$", re.MULTILINE)
 _ANALYSIS_SIDECAR_HEADING_RE = re.compile(
@@ -50,13 +51,18 @@ class UserResponseError(ValueError):
 
 
 @dataclass(frozen=True)
-class UserResponseApprovalRecord:
-    """sidecar 의 ``## APPROVAL`` 블록 + 매칭에 필요한 frontmatter 필드."""
-    approved: bool
+class PlanDecisionRecord:
+    """sidecar 의 ``## PLAN DECISION`` 블록 + 매칭에 필요한 frontmatter 필드."""
+    status: str
     implementation_option: str
+    reason: str
     source_report: str
     seq: str
 
+    @property
+    def approved(self) -> bool:
+        return self.status == PLAN_DECISION_APPROVED
+
 
 @dataclass(frozen=True)
 class AnalysisReviewRecord:
@@ -353,31 +359,37 @@ def load_authoritative_analysis_review(
     return review
 
 
-def parse_user_response_approval(
-    sidecar_text: str,
-) -> Optional[UserResponseApprovalRecord]:
-    """``## APPROVAL`` 블록이 ``- Approved: true`` 를 가질 때만 record 를
-    반환한다. 옵션 라인은 블록 내부에서만 읽는다 (다른 응답 본문의 우연한
-    동일 문구를 옵션으로 오인하지 않도록).
+_PLAN_DECISION_STATUS_RE = re.compile(
+    r"^- Status:\s*(approved|revision-requested|rejected)\s*$", re.MULTILINE
+)
+
+
+def parse_plan_decision(sidecar_text: str) -> Optional[PlanDecisionRecord]:
+    """``## PLAN DECISION`` 블록을 읽어 record 로 돌려준다. 승인·재작업·반려를
+    구분하지 않고 그대로 싣는다 — 어느 판정을 받아들일지는 소비 측 정책이다.
+    옵션·사유 라인은 블록 내부에서만 읽는다 (다른 응답 본문의 우연한 동일
+    문구를 옵션으로 오인하지 않도록).
 
-    strictness 는 의도적이다: producer 출력과 byte-identical 한 소문자
-    ``true`` 만 인정하며, 손편집 변형(``TRUE``/``True``)은 fail-closed 로
+    strictness 는 의도적이다: producer 출력과 byte-identical 한 소문자 status
+    만 인정하며, 손편집 변형(``Approved``/``REJECTED``)은 fail-closed 로
     불인정한다."""
-    m = _APPROVAL_HEADING_RE.search(sidecar_text)
+    m = _PLAN_DECISION_HEADING_RE.search(sidecar_text)
     if not m:
         return None
     block = sidecar_text[m.end():]
     nxt = _NEXT_RESPONSE_HEADING_RE.search(block)
     if nxt:
         block = block[: nxt.start()]
-    if re.search(r"^- Approved:\s*true\s*$", block, re.MULTILINE) is None:
+    status = _PLAN_DECISION_STATUS_RE.search(block)
+    if status is None:
         return None
     om = re.search(r"^- Implementation-Option:\s*(\S.*?)\s*$", block, re.MULTILINE)
     sm = re.search(r"^seq:\s*(\S+)\s*$", sidecar_text, re.MULTILINE)
     rm = re.search(r"^source-report:\s*(\S.*?)\s*$", sidecar_text, re.MULTILINE)
-    return UserResponseApprovalRecord(
-        approved=True,
+    return PlanDecisionRecord(
+        status=status.group(1),
         implementation_option=om.group(1) if om else "",
+        reason=_quoted_review_value(block, "Reason"),
         source_report=rm.group(1) if rm else "",
         seq=sm.group(1) if sm else "",
     )
@@ -404,8 +416,8 @@ def _value(block: str) -> str:
 
 def parse_user_response_entries(sidecar_text: str) -> list[UserResponseEntry]:
     """Reverse of ``serialize_user_response`` for the per-response ``## C-*``
-    blocks. The ``## APPROVAL`` block is skipped (read separately by
-    ``parse_user_response_approval``)."""
+    blocks. The ``## PLAN DECISION`` block is skipped (read separately by
+    ``parse_plan_decision``)."""
     entries: list[UserResponseEntry] = []
     matches = list(_RESPONSE_HEADING_RE.finditer(sidecar_text))
     for i, m in enumerate(matches):
@@ -581,7 +593,7 @@ def show_open_rows(report_path: Path) -> dict:
 
 
 def write_sidecar(report_path: Path, answers: list[dict],
-                  approval: Optional[dict], created_at: str,
+                  plan_decision: Optional[dict], created_at: str,
                   task_key: str = "") -> Path:
     run_meta = infer_run_meta(report_path, task_key=task_key or None)
     out_dir = user_responses_dir_for_report(report_path)
@@ -597,13 +609,15 @@ def write_sidecar(report_path: Path, answers: list[dict],
             response_id=a["id"], kind=a.get("kind", ""), value=a["value"],
             rationale=a.get("rationale"), disposition=a.get("disposition", "answer"))
 
-    appr = None
-    if approval and approval.get("approved"):
-        appr = UserResponseApproval(
-            approved=True, implementation_option=approval.get("implementationOption", ""))
+    decision = None
+    if plan_decision and plan_decision.get("status"):
+        decision = UserPlanDecision(
+            status=plan_decision["status"],
+            implementation_option=plan_decision.get("implementationOption", ""),
+            reason=plan_decision.get("reason", ""))
     sidecar.write_text(
         serialize_user_response(run_meta=run_meta, entries=list(merged.values()),
-                                created_at=created_at, approval=appr),
+                                created_at=created_at, plan_decision=decision),
         encoding="utf-8")
     return sidecar
 
@@ -623,7 +637,9 @@ def main(argv: Optional[list[str]] = None) -> int:
     pw = sub.add_parser("write")
     pw.add_argument("--report", required=True)
     pw.add_argument("--answers", required=True, help="JSON array of answer entries")
-    pw.add_argument("--approval", default="", help="JSON approval object")
+    pw.add_argument(
+        "--plan-decision", default="",
+        help='JSON plan decision, e.g. {"status":"rejected","reason":"..."}')
     pw.add_argument("--task-key", default="", help="task-key from list/show context")
 
     ns = parser.parse_args(argv)
@@ -636,9 +652,9 @@ def main(argv: Optional[list[str]] = None) -> int:
         return 0
     if ns.cmd == "write":
         answers = json.loads(ns.answers)
-        approval = json.loads(ns.approval) if ns.approval else None
+        decision = json.loads(ns.plan_decision) if ns.plan_decision else None
         created_at = dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-        p = write_sidecar(Path(ns.report), answers, approval, created_at,
+        p = write_sidecar(Path(ns.report), answers, decision, created_at,
                           task_key=ns.task_key)
         json.dump({"sidecar": str(p)}, sys.stdout, ensure_ascii=False)
         return 0

package/runtime/python/okstra_ctl/wizard.py

@@ -29,6 +29,23 @@ from datetime import datetime
 from pathlib import Path
 from typing import Any, Callable, Optional
 
+from okstra_ctl.application.advance_wizard import plan_prompt
+from okstra_ctl.application.resolve_assignment import resolve_lead_provider
+from okstra_ctl.domain.host import (
+    HostCapabilityMismatch,
+    HostNotRegistered,
+    HostSessionContext,
+    ProviderUnavailable,
+)
+from okstra_ctl.domain.wizard.interaction import (
+    InteractionPlan,
+    WizardAnswerError,
+    WizardOption,
+    WizardPrompt,
+    normalize_planned_answer,
+)
+from okstra_ctl.registry.host_registry import default_host_registry
+from okstra_ctl.registry.provider_registry import default_provider_registry
 from okstra_ctl.ids import slugify_task_segment
 from okstra_ctl.brief_frontmatter import read_brief_frontmatter
 from okstra_ctl.analysis_inputs import (
@@ -44,13 +61,12 @@ from okstra_ctl.analysis_inputs import (
 from okstra_ctl.models import (
     PROVIDER_MAPPINGS,
     UnknownModelError,
+    UnknownProviderError,
     picker_options,
     provider_ids,
     provider_supports_role,
     resolve_model_metadata,
 )
-from okstra_ctl.lead_runtime import lead_runtime_info
-from okstra_ctl.runner_resolution import native_provider_for_host
 from okstra_ctl.clarification_items import (
     scan_approval_gate,
     sidecar_answers,
@@ -85,8 +101,8 @@ from okstra_ctl.stage_map import (
     stage_map_records,
 )
 from okstra_ctl.user_response import (
-    UserResponseApprovalRecord,
-    parse_user_response_approval,
+    PlanDecisionRecord,
+    parse_plan_decision,
 )
 from okstra_ctl.workers import (
     ALLOWED_WORKERS,
@@ -176,7 +192,6 @@ _BRIEF_ENTRY_TASK_TYPES = (
 
 CANONICAL_BASE_REFS = ["main", "dev", "staging", "preprod", "prod"]
 BASE_REF_FREE_INPUT_TOKEN = "__free_input__"
-HOST_PICK_OPTION_CAP = 4
 
 CLAUDE_MODEL_OPTIONS = ["default", *picker_options("claude")]
 CODEX_MODEL_OPTIONS = ["default", *picker_options("codex")]
@@ -389,6 +404,8 @@ class WizardState:
     project_root: str = ""
     project_id: str = ""
     host_runtime: str = "claude-code"
+    host_entry_mode: str = "current-session"
+    available_functions: list[str] = field(default_factory=list)
 
     # task identity
     is_new_task: Optional[bool] = None
@@ -535,8 +552,6 @@ class Prompt:
             "echoTemplate": self.echo_template,
             "multi": self.multi,
         }
-        if self.kind == "pick" and len(self.options) > HOST_PICK_OPTION_CAP:
-            out["presentation"] = "numbered-text"
         if self.kind == "pick_group":
             out["questions"] = [
                 {"step": q.step, "label": q.label,
@@ -551,35 +566,6 @@ class WizardError(Exception):
     """validation failure surfaced to user."""
 
 
-def _normalize_numbered_pick_item(prompt: Prompt, answer: str) -> str:
-    candidate = (answer or "").strip()
-    exact_values = [option.value for option in prompt.options if option.value == candidate]
-    if exact_values:
-        return exact_values[0]
-
-    if candidate.isdecimal():
-        number = int(candidate)
-        if 1 <= number <= len(prompt.options):
-            return prompt.options[number - 1].value
-        raise WizardError(f"numbered-text answer is out of range: {candidate}")
-
-    label_values = [option.value for option in prompt.options if option.label == candidate]
-    if len(label_values) == 1:
-        return label_values[0]
-    if len(label_values) > 1:
-        raise WizardError(f"numbered-text answer label is ambiguous: {candidate}")
-    raise WizardError(f"numbered-text answer is not an option: {candidate}")
-
-
-def _normalize_numbered_pick_answer(prompt: Prompt, answer: str) -> str:
-    if prompt.multi:
-        return ",".join(
-            _normalize_numbered_pick_item(prompt, item)
-            for item in (answer or "").split(",")
-        )
-    return _normalize_numbered_pick_item(prompt, answer)
-
-
 # ---- Validation helpers --------------------------------------------------
 
 _SLUG_OK = re.compile(r"[a-z0-9]")
@@ -696,23 +682,27 @@ def _approve_plan_in_place(plan_path: Path) -> None:
 
 def _find_html_approval_sidecar(
     plan_path: Path,
-) -> Optional[tuple[Path, UserResponseApprovalRecord]]:
-    """plan 의 run 디렉토리 sibling ``user-responses/`` 에서 APPROVAL 블록을
-    가진 sidecar 를 찾는다. source-report 파일명과 seq 가 plan 과 일치해야
-    하며, 복수면 mtime 최신을 택한다."""
+) -> Optional[tuple[Path, PlanDecisionRecord]]:
+    """plan 의 run 디렉토리 sibling ``user-responses/`` 에서 승인 판정을 담은
+    sidecar 를 찾는다. source-report 파일명과 seq 가 plan 과 일치해야 하며,
+    복수면 mtime 최신을 택한다.
+
+    승인이 아닌 판정(반려·재작업 요청)은 여기서 걸러진다 — 이 단계가 묻는 것은
+    "사용자가 이 plan 을 승인해 두었는가" 뿐이고, 반려 사유는 다음 planning
+    run 이 sidecar 를 통째로 읽어 처리한다."""
     responses_dir = plan_path.parent.parent / "user-responses"
     if not responses_dir.is_dir():
         return None
     m = re.search(r"-(\d+)\.md$", plan_path.name)
     plan_seq = m.group(1) if m else ""
-    best: Optional[tuple[float, Path, UserResponseApprovalRecord]] = None
+    best: Optional[tuple[float, Path, PlanDecisionRecord]] = None
     for f in sorted(responses_dir.glob("user-response-*.md")):
         try:
             text = f.read_text(encoding="utf-8", errors="replace")
         except OSError:
             continue
-        rec = parse_user_response_approval(text)
-        if rec is None or rec.seq != plan_seq:
+        rec = parse_plan_decision(text)
+        if rec is None or not rec.approved or rec.seq != plan_seq:
             continue
         if Path(rec.source_report).name != plan_path.name:
             continue
@@ -3369,6 +3359,28 @@ def _build_reuse_previous(state: WizardState) -> Prompt:
     )
 
 
+def _restore_reused_lead(state: WizardState, inputs: dict) -> None:
+    requested_provider = _safe_provider(inputs.get("leadProvider"), "lead")
+    try:
+        assignment = resolve_lead_provider(
+            host_id=state.host_runtime,
+            requested_provider=requested_provider,
+            host_registry=default_host_registry(),
+            provider_registry=default_provider_registry(),
+        )
+    except (
+        HostCapabilityMismatch,
+        HostNotRegistered,
+        ProviderUnavailable,
+        UnknownProviderError,
+    ) as exc:
+        raise WizardError(
+            f"previous run cannot be reused: {exc}; choose step-by-step re-entry"
+        ) from exc
+    state.lead_provider = assignment.provider
+    state.lead_model = _safe_model(assignment.provider, inputs.get("leadModel"))
+
+
 def _submit_reuse_previous(state: WizardState, value: str) -> Optional[str]:
     if value not in ("yes", "no"):
         raise WizardError(f"expected 'yes' or 'no', got: {value!r}")
@@ -3383,16 +3395,7 @@ def _submit_reuse_previous(state: WizardState, value: str) -> Optional[str]:
     state.workers_override = (
         ",".join(w for w in workers if isinstance(w, str))
         if isinstance(workers, list) else "")
-    state.lead_provider = _safe_provider(inputs.get("leadProvider"), "lead")
-    lead_provider = state.lead_provider or "claude"
-    native_provider = native_provider_for_host(state.host_runtime)
-    if native_provider and lead_provider != native_provider:
-        raise WizardError(
-            f"previous run used provider {lead_provider!r}, but "
-            f"{state.host_runtime} requires provider {native_provider!r}; "
-            "choose step-by-step re-entry"
-        )
-    state.lead_model = _safe_model(lead_provider, inputs.get("leadModel"))
+    _restore_reused_lead(state, inputs)
     state.claude_model = _safe_model("claude", inputs.get("claudeModel"))
     state.codex_model = _safe_model("codex", inputs.get("codexModel"))
     state.antigravity_model = _safe_model("antigravity", inputs.get("antigravityModel"))
@@ -3601,16 +3604,27 @@ def _model_pick(step: str, label: str, options: list[str], echo: str) -> Prompt:
 
 
 def _qualified_role_model_options(role: str) -> list[str]:
-    options = list(CLAUDE_MODEL_OPTIONS)
-    for provider in provider_ids(role):
+    registry = default_provider_registry()
+    options = ["default", *_provider_picker_options("claude", registry)]
+    for provider in registry.ids(role):
         if provider == "claude":
             continue
         options.extend(
-            f"{provider}:{model}" for model in picker_options(provider)
+            f"{provider}:{model}"
+            for model in _provider_picker_options(provider, registry)
         )
     return options
 
 
+def _provider_picker_options(provider: str, registry=None) -> list[str]:
+    provider_registry = registry or default_provider_registry()
+    return [
+        alias
+        for alias, model in provider_registry.resolve(provider).models.items()
+        if model.in_picker
+    ]
+
+
 def _submit_qualified_role_model(
     state: WizardState, value: str, role: str, model_field: str, provider_field: str,
 ) -> str:
@@ -3629,32 +3643,44 @@ def _submit_qualified_role_model(
 
 def _build_lead_model(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "lead_model")
-    provider = native_provider_for_host(state.host_runtime)
+    provider = default_host_registry().resolve(
+        state.host_runtime
+    ).descriptor.native_provider_id
     options = (
-        ["default", *picker_options(provider)]
+        ["default", *_provider_picker_options(provider)]
         if provider else _qualified_role_model_options("lead")
     )
     return _model_pick(S_LEAD_MODEL, t["label"], options, t["echo_template"])
 
 
 def _submit_lead_model(state: WizardState, value: str) -> Optional[str]:
-    native_provider = native_provider_for_host(state.host_runtime)
+    native_provider = default_host_registry().resolve(
+        state.host_runtime
+    ).descriptor.native_provider_id
     if native_provider:
         raw = (value or "").strip()
+        requested_provider = ""
         if ":" in raw:
-            selected_provider, raw = (
+            requested_provider, raw = (
                 part.strip().lower() for part in raw.split(":", 1)
             )
-            if selected_provider != native_provider:
-                host_label = lead_runtime_info(state.host_runtime).agent_label
-                raise WizardError(
-                    f"{host_label.removesuffix(' CLI')} host requires provider "
-                    f"{native_provider!r} "
-                    "for the in-session lead"
-                )
-        state.lead_provider = native_provider
-        state.lead_model = _validate_model(native_provider, raw)
-        return f"lead-model: {native_provider}:{state.lead_model or 'default'}"
+        try:
+            assignment = resolve_lead_provider(
+                host_id=state.host_runtime,
+                requested_provider=requested_provider,
+                host_registry=default_host_registry(),
+                provider_registry=default_provider_registry(),
+            )
+        except (
+            HostCapabilityMismatch,
+            HostNotRegistered,
+            ProviderUnavailable,
+            UnknownProviderError,
+        ) as exc:
+            raise WizardError(str(exc)) from exc
+        state.lead_provider = assignment.provider
+        state.lead_model = _validate_model(assignment.provider, raw)
+        return f"lead-model: {assignment.provider}:{state.lead_model or 'default'}"
     selected = _submit_qualified_role_model(
         state, value, "lead", "lead_model", "lead_provider",
     )
@@ -4529,6 +4555,8 @@ def _reset_field(state: WizardState, fname: str) -> None:
 def init_state(
     *, workspace_root: str, project_root: str, project_id: str,
     host_runtime: str = "claude-code",
+    host_entry_mode: str = "current-session",
+    available_functions: Optional[list[str]] = None,
 ) -> WizardState:
     """Bootstrap a new wizard state."""
     return WizardState(
@@ -4536,6 +4564,8 @@ def init_state(
         project_root=project_root,
         project_id=project_id,
         host_runtime=host_runtime,
+        host_entry_mode=host_entry_mode,
+        available_functions=list(available_functions or []),
     )
 
 
@@ -4668,9 +4698,73 @@ def _screen_progress(state: WizardState) -> dict[str, Any]:
     }
 
 
+def _domain_prompt(prompt: Prompt) -> WizardPrompt:
+    return WizardPrompt(
+        step=prompt.step,
+        kind=prompt.kind,
+        label=prompt.label,
+        options=tuple(
+            WizardOption(option.value, option.label, option.description)
+            for option in prompt.options
+        ),
+        help=prompt.help,
+        echo_template=prompt.echo_template,
+        multi=prompt.multi,
+        questions=tuple(_domain_prompt(question) for question in prompt.questions),
+    )
+
+
+def _interaction_plan(state: WizardState, prompt: Prompt) -> InteractionPlan:
+    context = HostSessionContext(
+        host_id=state.host_runtime,
+        entry_mode=state.host_entry_mode,
+        available_functions=frozenset(state.available_functions),
+        interaction_surface="terminal",
+    )
+    adapter = default_host_registry().resolve(state.host_runtime)
+    return plan_prompt(_domain_prompt(prompt), context, adapter.interaction()).interaction
+
+
+def _interaction_payload(plan: InteractionPlan) -> dict[str, Any]:
+    return {
+        "kind": plan.kind,
+        "answerProtocol": {
+            "kind": plan.answer_protocol.kind,
+            "multi": plan.answer_protocol.multi,
+        },
+    }
+
+
+def _normalize_interaction_answer(
+    state: WizardState,
+    prompt: Prompt,
+    plan: InteractionPlan,
+    value: str,
+) -> str:
+    try:
+        return normalize_planned_answer(
+            _domain_prompt(prompt),
+            plan.answer_protocol,
+            value,
+        )
+    except WizardAnswerError as exc:
+        is_legacy_raw_answer = (
+            not state.available_functions
+            and "not an option" in str(exc)
+            and not (value or "").strip().isdecimal()
+        )
+        if is_legacy_raw_answer:
+            return value
+        raise WizardError(str(exc)) from exc
+
+
 def prompt_payload(state: WizardState, prompt: Prompt) -> dict[str, Any]:
     """Prompt JSON 에 진행 카운터를 덧붙인다. done/aborted 는 progress 를 생략."""
     out = prompt.to_json()
+    plan = _interaction_plan(state, prompt)
+    out["interaction"] = _interaction_payload(plan)
+    if plan.kind in {"numbered-single", "numbered-multi"}:
+        out["presentation"] = "numbered-text"
     if prompt.kind not in ("done", "aborted"):
         out["progress"] = _screen_progress(state)
     return out
@@ -4711,10 +4805,10 @@ def submit(state: WizardState, value: str) -> dict[str, Any]:
     prompt = next_prompt(state)
     if prompt.kind in ("done", "aborted"):
         return {"echo": "", "next": prompt_payload(state, prompt)}
+    plan = _interaction_plan(state, prompt)
+    value = _normalize_interaction_answer(state, prompt, plan, value)
     if prompt.kind == "pick_group":
         return _submit_group(state, prompt, value)
-    if prompt.kind == "pick" and len(prompt.options) > HOST_PICK_OPTION_CAP:
-        value = _normalize_numbered_pick_answer(prompt, value)
     step = STEP_BY_ID[prompt.step]
     echo = step.submit(state, value or "")
     if prompt.step not in state.answered:
@@ -5048,8 +5142,14 @@ def _cli(argv: list[str]) -> int:
     p_init.add_argument(
         "--host-runtime",
         default="claude-code",
-        choices=("claude-code", "codex", "antigravity", "external"),
+        choices=default_host_registry().ids(),
+    )
+    p_init.add_argument(
+        "--entry-mode",
+        default="current-session",
+        choices=("spawn-process", "current-session"),
     )
+    p_init.add_argument("--available-function", action="append", default=[])
     p_init.add_argument("--critic", default="")
 
     p_step = sub.add_parser("step")
@@ -5079,6 +5179,8 @@ def _cli(argv: list[str]) -> int:
             project_root=args.project_root,
             project_id=args.project_id,
             host_runtime=args.host_runtime,
+            host_entry_mode=args.entry_mode,
+            available_functions=args.available_function,
         )
         if args.critic:
             state.critic = args.critic

package/runtime/python/okstra_ctl/worker_audit_ledger.py

@@ -29,8 +29,13 @@ READING_CONFIRMATION_HEADING_RE = re.compile(
     r"^##[ \t]+0\.[ \t]+Reading Confirmation\b", re.MULTILINE
 )
 
+# The row's prefix opens it and the end of the line closes it, so the backticks
+# the template prescribes are decoration and are accepted either way. Requiring
+# them once cost a run: a worker wrote six correct paths bare, none of the rows
+# parsed, and every citation it made read as unbacked — a file it demonstrably
+# opened counted as unread over markdown punctuation.
 _EVIDENCE_READ_RE = re.compile(
-    r"^- Evidence read: `(?P<path>[^`\n]+)`\s*$",
+    r"^- Evidence read: `?(?P<path>[^`\n]+?)`?\s*$",
     re.MULTILINE,
 )
 _FILE_LINE_CITATION_RE = re.compile(
@@ -106,17 +111,37 @@ def _evidence_read_ledger_failures(
     except OSError as exc:
         return [f"worker audit sidecar unreadable: {audit_path.name} ({exc})"]
 
-    missing_paths = sorted(
-        _cited_file_paths(result_content) - _audit_evidence_read_paths(audit_content)
-    )
+    read_paths = _audit_evidence_read_paths(audit_content)
+    missing_paths = sorted(_cited_file_paths(result_content) - read_paths)
     return [
         f"worker `{worker_role}` result `{result_name}` cites "
         f"`{missing_path}:line` without an Evidence read row for "
         f"`{missing_path}` in `{audit_path.name}`"
+        + _ledger_path_hint(missing_path, read_paths)
         for missing_path in missing_paths
     ]
 
 
+def _ledger_path_hint(cited_path: str, read_paths: set[str]) -> str:
+    """What to cite instead, when the ledger plainly holds the same file.
+
+    A worker that cites the full path once and the bare filename afterwards
+    reads to this check as never having opened the file, and the bare failure
+    text sends the reader looking for a missing read that is not missing. One
+    unambiguous ledger row makes the remedy a rewritten citation; two rows
+    ending the same way make it a guess, so those say nothing.
+    """
+    if "/" in cited_path:
+        return ""
+    same_name = [path for path in read_paths if path.rsplit("/", 1)[-1] == cited_path]
+    if len(same_name) != 1:
+        return ""
+    return (
+        f" — the ledger records it as `{same_name[0]}`; cite that "
+        f"project-relative path, not the bare filename"
+    )
+
+
 def _result_files(run_dir: Path, task_type: str, seq: str | None, worker: str | None):
     """Every worker-results file in *run_dir* this check owns, in name order."""
     for path in sorted((run_dir / "worker-results").glob("*.md")):

package/runtime/python/okstra_ctl/worker_prompt_policy.py

@@ -81,6 +81,13 @@ def resolve_prompt_plan(
         raise ValueError("worker ID is required")
     if dispatch_kind.startswith("reverify-r"):
         return _plan("reverify")
+    # A critic pass keeps the full analysis contract — worker anchor headers, the
+    # audit sidecar, the packet boundary — but is exempt from the equality group.
+    # Its body is deliberately unlike the initial one (it asks for coverage gaps
+    # and unrequested work, not findings), so grouping it with the initial
+    # analysis prompts makes `validate_analysis_prompt_set` compare two prompts
+    # that are *supposed* to differ and fail every critic-enabled run.
+    analysis_equality_group = None if dispatch_kind == "critic" else "analysis-core"
     if task_type == "implementation" and not executor_worker_id:
         raise ValueError("implementation executor worker ID is required")
     if worker_id == "report-writer":
@@ -101,7 +108,7 @@ def resolve_prompt_plan(
     if task_type == "final-verification":
         return _plan(
             "analysis",
-            equality_group="analysis-core",
+            equality_group=analysis_equality_group,
             packet_only=True,
             required_headers=FINAL_VERIFICATION_HEADERS,
             max_body_lines=96,
@@ -110,11 +117,11 @@ def resolve_prompt_plan(
     if task_type == "improvement-discovery":
         return _plan(
             "analysis",
-            equality_group="analysis-core",
+            equality_group=analysis_equality_group,
             packet_only=True,
             required_headers=(GRILLING_LOG_HEADER,),
         )
-    return _plan("analysis", equality_group="analysis-core", packet_only=True)
+    return _plan("analysis", equality_group=analysis_equality_group, packet_only=True)
 
 
 def resolve_prompt_plan_for_manifest(