okstra 0.201.2 → 0.202.0

package/runtime/python/okstra_ctl/agent/evidence_recovery.py

@@ -0,0 +1,78 @@
+"""종결된 호출의 결과를 보존하는 증거 보완 프롬프트 발행."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .invocation import (
+    AgentInstruction, AgentInstructionSource, AgentInvocationError,
+    AgentInvocationRequest, PreparedAgentInvocation, _extract_anchor_lines,
+    _split_prompt, agent_model_assignment_from_payload, invocation_metadata_identity,
+    prepare_agent_invocation, verify_agent_invocation,
+)
+from ..json_boundary import load_owned_object
+from ..worker_artifact_paths import audit_sidecar_rel
+
+
+def prepare_evidence_recovery(
+    metadata_path: Path, *, project_root: Path, result_path: Path,
+    source_attempt: int,
+) -> tuple[PreparedAgentInvocation, Path]:
+    """원래 모델·역할을 유지하고 새 결과 경로에 제한된 증거 보완을 발행한다."""
+    metadata = load_owned_object(metadata_path, artifact="recovery source metadata")
+    source = metadata["contractSource"]
+    manifest = project_root / source["runManifestPath"]
+    errors = verify_agent_invocation(
+        metadata_path, project_root=project_root, expected_run_manifest_path=manifest,
+    )
+    if errors:
+        raise AgentInvocationError("invalid recovery source: " + "; ".join(errors))
+    identity = invocation_metadata_identity(metadata)
+    if identity is None or not result_path.is_file():
+        raise AgentInvocationError("evidence recovery requires v2 identity and an existing result")
+    suffix = f"-evidence-recovery-{source_attempt}"
+    invocation_id = identity.invocation_ref + suffix
+    old_prompt = project_root / metadata["prompt"]["path"]
+    prompt = old_prompt.with_name(old_prompt.stem + suffix + old_prompt.suffix)
+    result = result_path.with_name(result_path.name.replace("-worker-", suffix + "-worker-", 1))
+    prefix, _ = _split_prompt(old_prompt.read_text(encoding="utf-8"))
+    replacements = {
+        "**Prompt History Path:**": str(prompt.relative_to(project_root)),
+        "Assigned worker prompt history path:": str(prompt),
+        "**Result Path:**": str(result.relative_to(project_root)),
+        "**Worker Result Path:**": str(result.relative_to(project_root)),
+        "**Audit sidecar path:**": audit_sidecar_rel(str(result)),
+    }
+    anchors = tuple(next((f"{key} {value}" for key, value in replacements.items()
+                          if line.startswith(key)), line) for line in _extract_anchor_lines(prefix))
+    body = _recovery_instructions(identity.invocation_ref, source_attempt, result_path, old_prompt)
+    prepared = prepare_agent_invocation(AgentInvocationRequest(
+        invocation_id=invocation_id, worker_id=None, audience=metadata["audience"],
+        assignment_ref=metadata["assignmentRef"], purpose=None,
+        assignment=agent_model_assignment_from_payload(metadata["modelAssignment"]),
+        instruction=AgentInstruction(anchor_lines=anchors, body=body, source_paths=(
+            AgentInstructionSource("project", str(result_path.relative_to(project_root))),)),
+        project_root=project_root, run_manifest_path=manifest,
+        duty_root=project_root / source["dutyRootPath"], prompt_path=prompt,
+        metadata_path=prompt.with_name(prompt.name + ".meta.json"),
+        dispatch_kind=metadata["dispatchKind"], participant_ref=identity.participant_ref,
+        role_execution_ref=identity.role_execution_ref, duty_id=identity.duty_id,
+        invocation_ref=invocation_id, attempt=1,
+    ))
+    return prepared, result
+
+
+def _recovery_instructions(invocation_ref: str, source_attempt: int, result_path: Path, old_prompt: Path) -> str:
+    """완료된 구현을 재실행하지 않는 보완 범위를 전달한다."""
+    return (
+        "## Evidence recovery scope\n\n"
+        f"Original invocation: {invocation_ref}; attempt: {source_attempt}.\n"
+        f"Read and preserve the original result: {result_path}.\n"
+        f"Read the original audit: {old_prompt}.mutation-audit.json.\n"
+        "The prior attempt failed only on a declaration discrepancy. Preserve existing source and QA work. "
+        "Do not repeat completed implementation steps or edit production source. Reconcile the declaration "
+        "and required evidence against current artifacts; retain historical validation as historical. "
+        "Do not invent a missing before-state or claim independent verification. If a substantive defect "
+        "or authority problem is found, report it for the lead instead of expanding this repair. "
+        "Write a new completion result in the original role's required format, citing the original result "
+        "and clearly separating recovered evidence from remaining independent checks.\n"
+    )

package/runtime/python/okstra_ctl/convergence_critic_prompt.py

@@ -28,7 +28,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Mapping, Sequence
 
-from .convergence_provenance import worker_result_suffix
+from .convergence_provenance import worker_result_paths, worker_result_suffix
 from .fixed_text import line
 from .json_boundary import JsonBoundaryError, load_owned_object
 from .paths import RunRef
@@ -132,9 +132,7 @@ def analyser_results(
 ) -> list[AnalyserResult]:
     """분석 audience 워커마다 결과 파일 경로와 finding id 를 짝지어 돌려준다.
 
-    결과 파일명은 `convergence_provenance` 가 이미 소유한 규칙을 그대로 쓴다 —
-    `<worker>-worker-<task-type>-<workerResults seq>.md`. state 시퀀스와 다른
-    카운터라 그룹 파일명에서 접미사를 빌려 오면 빗나간다.
+    출처 검사와 같은 실행 원장을 사용해야 교정 전 결과를 재검증하지 않는다.
     """
     suffix = worker_result_suffix(Path(run_dir), groups)
     if suffix is None:
@@ -142,13 +140,13 @@ def analyser_results(
             "cannot resolve the worker-result suffix from the grouping's "
             "runManifestPath"
         )
-    results_dir = Path(run_dir) / "worker-results"
+    paths = worker_result_paths(Path(run_dir), groups, suffix)
     by_worker = _findings_by_worker(groups)
     return [
         AnalyserResult(
             worker_id=worker,
             result_path=_project_relative(
-                project_root, results_dir / f"{worker}-worker-{suffix}.md"
+                project_root, paths[worker]
             ),
             finding_ids=tuple(by_worker.get(worker, ())),
         )

package/runtime/python/okstra_ctl/convergence_provenance.py

@@ -21,6 +21,8 @@ from pathlib import Path
 from typing import Mapping
 
 from okstra_ctl.convergence_engine import grouped_input_digest
+from okstra_ctl.execution_identity import Attempt, ExecutionManifest
+from okstra_ctl.execution_manifest import read_execution_manifest_view
 from okstra_ctl.json_boundary import (
     load_owned_object,
 )
@@ -97,6 +99,66 @@ def groups_digest_ok(state_dir: Path, suffix: str, document: dict) -> bool:
     return grouped_input_digest(document) == recorded
 
 
+def discovery_attempts(manifest: ExecutionManifest) -> dict[str, list[Attempt]]:
+    """교정 실행은 발견 결과를 대체하지만 재검증 투표는 발견 출처가 아니다."""
+    latest: dict[str, Attempt] = {}
+    for attempt in manifest.attempts:
+        current = latest.get(attempt.invocation_ref)
+        if current is None or attempt.attempt > current.attempt:
+            latest[attempt.invocation_ref] = attempt
+    by_role: dict[str, list[Attempt]] = {}
+    for invocation in manifest.invocations:
+        if invocation.dispatch_kind not in {"initial", "correction"}:
+            continue
+        attempt = latest.get(invocation.invocation_ref)
+        if attempt is not None:
+            by_role.setdefault(invocation.role_execution_ref, []).append(attempt)
+    return by_role
+
+
+def worker_result_paths(
+    run_dir: Path, document: Mapping, suffix: str
+) -> dict[str, Path]:
+    """실행 원장의 채택된 발견 결과를 고른다. 구형 원장은 파일명 규칙을 쓴다."""
+    results_dir = run_dir / "worker-results"
+    workers = document.get("workers") or []
+    paths = {
+        row["workerId"]: results_dir / f"{row['workerId']}-worker-{suffix}.md"
+        for row in workers if isinstance(row, Mapping) and row.get("workerId")
+    }
+    if document.get("schemaVersion") != "2.0":
+        return paths
+    recorded = document.get("runManifestPath")
+    if not _nonempty_string(recorded):
+        return paths
+    manifest_path = run_dir / "manifests" / Path(recorded).name
+    manifest, authority = read_execution_manifest_view(manifest_path)
+    if manifest.legacy:
+        return paths
+    attempts = discovery_attempts(manifest)
+    for row in workers:
+        if not isinstance(row, Mapping) or not row.get("workerId"):
+            continue
+        accepted = [
+            attempt for attempt in attempts.get(row.get("sourceRoleExecutionRef"), [])
+            if attempt.status == "ok" and attempt.result_path
+        ]
+        if not accepted:
+            continue
+        candidate = Path(accepted[-1].result_path)
+        if not candidate.is_absolute():
+            project_root = authority.get("projectRoot")
+            if not _nonempty_string(project_root):
+                raise ValueError("relative accepted resultPath requires projectRoot")
+            candidate = Path(project_root) / candidate
+        if candidate.resolve().parent != results_dir.resolve():
+            raise ValueError(f"accepted resultPath is outside worker-results: {candidate}")
+        if not candidate.is_file():
+            raise ValueError(f"accepted resultPath is missing: {candidate}")
+        paths[row["workerId"]] = candidate
+    return paths
+
+
 def read_canonical_worker_result(
     worker_results_dir: Path, worker: str, suffix: str
 ) -> str | None:
@@ -140,20 +202,25 @@ def provenance_errors(
     claims = group_claims(document)
     if claims is None:
         return []
+    paths = worker_result_paths(worker_results_dir.parent, document, suffix)
     contents: dict[str, str | None] = {}
     errors: list[str] = []
     for finding_id, worker, item_id in claims:
         if worker not in contents:
-            contents[worker] = read_canonical_worker_result(
-                worker_results_dir, worker, suffix
-            )
+            candidate = paths.get(worker)
+            if candidate is not None and candidate.name != f"{worker}-worker-{suffix}.md":
+                contents[worker] = candidate.read_text(encoding="utf-8")
+            else:
+                contents[worker] = read_canonical_worker_result(
+                    worker_results_dir, worker, suffix
+                )
         text = contents[worker]
         if text is None or id_occurs_wordbounded(text, item_id):
             continue
         errors.append(
             f"convergence groups `{groups_label}` group {finding_id} "
             f"cites source item `{worker}:{item_id}`, but that ID does not "
-            f"occur in the worker's result file `{worker}-worker-{suffix}.md` — a "
+            f"occur in the worker's result file `{paths.get(worker, Path(f'{worker}-worker-{suffix}.md')).name}` — a "
             "grouping may not invent a provenance link to an item the "
             "worker never reported."
         )
@@ -243,10 +310,10 @@ DISCARDED_ATTEMPT_STATUSES = frozenset(
 
 
 def discarded_workers(document: object, execution_manifest: object) -> dict[str, str]:
-    """``{workerId: "<invocationRef>#<attempt> <status>"}`` — 초기 attempt 가 전부
+    """``{workerId: "<invocationRef>#<attempt> <status>"}`` — 발견 attempt 가 전부
     폐기돼 채택할 결과가 없는 분석 워커.
 
-    한 워커의 초기 invocation 이 둘 이상이면(교정 디스패치는 새 invocation 이다)
+    한 워커의 발견 invocation 이 둘 이상이면(교정 디스패치는 새 invocation 이다)
     그중 하나라도 마지막 attempt 가 ``ok`` 면 채택 가능한 결과가 있는 것이므로
     폐기로 보지 않는다. legacy 매니페스트나 v1 roster 는 판정하지 않는다.
     """
@@ -254,17 +321,7 @@ def discarded_workers(document: object, execution_manifest: object) -> dict[str,
         return {}
     if execution_manifest is None or getattr(execution_manifest, "legacy", False):
         return {}
-    initial_refs: dict[str, set[str]] = {}
-    for invocation in getattr(execution_manifest, "invocations", ()):
-        if invocation.dispatch_kind == "initial":
-            initial_refs.setdefault(invocation.role_execution_ref, set()).add(
-                invocation.invocation_ref
-            )
-    latest: dict[str, object] = {}
-    for attempt in getattr(execution_manifest, "attempts", ()):
-        current = latest.get(attempt.invocation_ref)
-        if current is None or attempt.attempt > current.attempt:
-            latest[attempt.invocation_ref] = attempt
+    attempts = discovery_attempts(execution_manifest)
     result: dict[str, str] = {}
     for row in document["workers"]:
         if not isinstance(row, dict):
@@ -273,7 +330,7 @@ def discarded_workers(document: object, execution_manifest: object) -> dict[str,
         role_ref = row.get("sourceRoleExecutionRef")
         if not _nonempty_string(worker) or not _nonempty_string(role_ref):
             continue
-        rows = [latest[ref] for ref in sorted(initial_refs.get(role_ref, ())) if ref in latest]
+        rows = attempts.get(role_ref, [])
         if not rows or any(item.status == "ok" for item in rows):
             continue
         discarded = [item for item in rows if item.status in DISCARDED_ATTEMPT_STATUSES]

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -13,6 +13,7 @@ from typing import Any, Mapping, Sequence
 
 from .dispatch_state import abandon_agent_dispatch_attempt
 from .agent.invocation import invocation_input_digest
+from .agent.evidence_recovery import prepare_evidence_recovery
 from .dispatch_state import (
     CompletedWithoutResultError,
     BACKEND_CLI_WRAPPER,
@@ -71,7 +72,7 @@ from .domain.worker_runtime import (
     WorkerSpawnRequest,
 )
 from .ports.worker_runtime import WorkerRuntimePort
-from .execution_identity import Attempt, Invocation, RoleExecution, model_spec_digest
+from .execution_identity import Attempt, ExecutionManifest, Invocation, RoleExecution
 from .execution_manifest import (
     ExecutionManifestError,
     finish_attempt_mutation,
@@ -153,7 +154,6 @@ _WRAPPER_LOG_TAIL_BYTES = 800
 class RevalidatedBinding:
     role_execution_ref: str
     binding: HostModelBinding
-    model_spec_digest: str
 
 
 def revalidate_role_execution(
@@ -165,7 +165,6 @@ def revalidate_role_execution(
     if (
         role_execution.model_ref is None
         or role_execution.binding is None
-        or role_execution.model_spec_digest is None
     ):
         raise DispatchError("model binding changed: role execution is unbound")
     try:
@@ -188,18 +187,16 @@ def revalidate_role_execution(
         binding = assignment.binding
         if binding is None:
             raise AssignmentResolutionError("selected model has no worker binding")
-        digest = model_spec_digest(pool.resolve(role_execution.model_ref), binding)
     except (ValueError, RuntimeError) as exc:
         raise DispatchError(f"model binding changed: {exc}") from exc
     identity_matches = (
         assignment.provider_id == role_execution.provider
         and assignment.model_id == role_execution.model_id
         and binding == role_execution.binding
-        and digest == role_execution.model_spec_digest
     )
     if not identity_matches:
         raise DispatchError("model binding changed for selected role execution")
-    return RevalidatedBinding(role_execution.role_execution_ref, binding, digest)
+    return RevalidatedBinding(role_execution.role_execution_ref, binding)
 
 
 def dispatch_revalidated_role_execution(
@@ -407,6 +404,9 @@ def build_dispatch_plan(
 
 
 def dispatch_plan(plan: DispatchPlan, *, wait: bool = True) -> int:
+    plan = _recover_declaration_failures(plan)
+    if not plan.jobs:
+        return 0
     plan = _ensure_runtime_chain(plan)
     _validate_report_writer_isolation(plan.jobs)
     _validate_implementation_phase_order(plan.jobs)
@@ -508,6 +508,9 @@ def dispatch_cli_wrapper_plan(plan: DispatchPlan) -> int:
     """Start one dependency-free CLI batch before collecting any worker."""
     if any(job.backend != BACKEND_CLI_WRAPPER for job in plan.jobs):
         raise DispatchError("concurrent CLI dispatch requires cli-wrapper jobs only")
+    plan = _recover_declaration_failures(plan)
+    if not plan.jobs:
+        return 0
     plan = _ensure_runtime_chain(plan)
     _validate_report_writer_isolation(plan.jobs)
     _validate_implementation_phase_order(plan.jobs)
@@ -1617,6 +1620,74 @@ def _spawn_cli_job_nonblocking(
     )
 
 
+def _recover_declaration_failures(plan: DispatchPlan) -> DispatchPlan:
+    """선언만으로 거부된 구현은 같은 호출을 재시도하지 않고 증거 보완으로 연결한다."""
+    if not any(job.has_execution_identity for job in plan.jobs):
+        return plan
+    manifest = read_execution_manifest(plan.manifest_path)
+    jobs: list[WorkerJob] = []
+    for job in plan.jobs:
+        source_attempt = _declaration_recovery_attempt(manifest, job)
+        if source_attempt is None:
+            jobs.append(job)
+            continue
+        recovered_ref = f"{job.invocation_ref}-evidence-recovery-{source_attempt}"
+        recovered = [row for row in manifest.attempts if row.invocation_ref == recovered_ref]
+        if recovered and max(recovered, key=lambda row: row.attempt).status == "ok":
+            continue
+        try:
+            prepared, result = prepare_evidence_recovery(
+                job.prompt_metadata_path, project_root=plan.project_root,
+                result_path=job.result_path, source_attempt=source_attempt,
+            )
+        except AgentInvocationError as exc:
+            raise DispatchError(f"evidence recovery could not be prepared: {exc}") from exc
+        jobs.append(replace(
+            job, invocation_id=prepared.invocation_id, invocation_ref=prepared.invocation_ref,
+            attempt=1, prompt_path=prepared.prompt_path, prompt_metadata_path=prepared.metadata_path,
+            result_path=result, worker_result_path=result, completion_paths=(result,),
+            result_aliases=(), instruction_digest=prepared.instruction_digest,
+            prompt_digest=prepared.prompt_digest,
+        ))
+        if not recovered:
+            _append_event(plan, "worker-evidence-recovery-prepared", {
+                "sourceInvocationRef": job.invocation_ref, "sourceAttempt": source_attempt,
+                "invocationRef": prepared.invocation_ref, "resultPath": str(result),
+                "modelExecutionValue": job.model_execution_value,
+            })
+    return replace(plan, jobs=tuple(jobs))
+
+
+def _declaration_recovery_attempt(manifest: ExecutionManifest, job: WorkerJob) -> int | None:
+    """선언 오류만 있는 종결 시도를 고르고 이미 시작한 후속 작업은 보존한다."""
+    prior = [row for row in manifest.attempts if row.invocation_ref == job.invocation_ref]
+    last = max(prior, key=lambda row: row.attempt) if prior else None
+    summary = last.change_summary if last else {}
+    if not (
+        job.audience == "implementation-executor" and last is not None
+        and last.finished_at is not None and last.status == "contract-failed-unattributed"
+        and summary.get("sourceChanged") is False and summary.get("gitChanged") is False
+        and summary.get("violations") == ["declared out-of-plan path did not change"]
+        and "-evidence-recovery-" not in job.invocation_ref
+    ):
+        return None
+    recovered_ref = f"{job.invocation_ref}-evidence-recovery-{last.attempt}"
+    later_refs = {
+        row.invocation_ref for row in manifest.invocations
+        if row.role_execution_ref == job.role_execution_ref
+        and row.invocation_ref not in (job.invocation_ref, recovered_ref)
+    }
+    later = [row for row in manifest.attempts if row.invocation_ref in later_refs
+             and row.started_at >= last.finished_at]
+    if later:
+        raise DispatchError(
+            "a subsequent invocation already exists for this role; collect or await "
+            f"{', '.join(sorted({row.invocation_ref for row in later}))} instead of redispatching "
+            f"the historical failure {job.invocation_ref}"
+        )
+    return last.attempt
+
+
 def _next_attempt(plan: DispatchPlan, job: WorkerJob) -> int:
     """이 invocation 이 다음에 청구할 attempt 번호.
 
@@ -1630,12 +1701,23 @@ def _next_attempt(plan: DispatchPlan, job: WorkerJob) -> int:
         return job.attempt
     manifest = read_execution_manifest(plan.manifest_path)
     prior = [
-        row.attempt for row in manifest.attempts
+        row for row in manifest.attempts
         if row.invocation_ref == job.invocation_ref
     ]
     if not prior:
         return job.attempt
-    spent = max(prior)
+    last = max(prior, key=lambda row: row.attempt)
+    if last.finished_at is None:
+        raise DispatchError(f"invocation is still running: {job.invocation_ref}; use okstra team await")
+    if last.status != "failed-no-mutation":
+        raise DispatchError(
+            f"invocation {job.invocation_ref} attempt {last.attempt} is already closed as {last.status}; "
+            "preserve its result and audit. Use okstra agent-prompt materialize with a new "
+            "--invocation-id and distinct --prompt/--result paths in the same run, retaining "
+            "--assignment-ref and the selected model. Scope the corrective instruction to "
+            "missing evidence or the verified defect; do not append another attempt or replay completed implementation."
+        )
+    spent = last.attempt
     if spent >= MAX_WORKER_ATTEMPTS:
         raise DispatchError(
             f"worker retry budget is spent: {job.invocation_ref} used "
@@ -2309,15 +2391,7 @@ def _audit_attempt(
 
 
 def _declared_out_of_plan_paths(result_path: Path) -> tuple[str, ...]:
-    """워커가 자기 결과의 `Out-of-plan edits` 블록에 선언한 경로.
-
-    감사는 워커가 끝나는 시점에 돈다. 그때 디스크에 있는 것은 워커 결과
-    마크다운뿐이고, `implementation.outOfPlanEdits` 는 리드가 나중에 쓰는 최종
-    리포트의 필드다. JSON 형태만 읽었기 때문에 executor 의 선언이 한 번도 보이지
-    않았고, 계약대로 선언한 편집까지 미허가 변경으로 집계됐다. 블록의 형태는 이
-    판독기를 위해 `_implementation-executor.md` 가 고정한다 — `- ` 줄마다 첫 백틱
-    토큰이 경로다.
-    """
+    """지원하는 결과 표기에서 참고 선언을 읽는다. 권한 판정에는 사용하지 않는다."""
     if not result_path.is_file() or result_path.suffix != ".md":
         return ()
     try:

package/runtime/python/okstra_ctl/execution_identity.py

@@ -283,10 +283,17 @@ def model_spec_digest(
     write_policy_digest: str | None = None,
     served_model_attestation: ServedModelAttestation | None = None,
 ) -> str:
-    """Digest preparation facts; invocation policy and observations are excluded."""
+    """실행 준비 사실을 해시하며 요금·호출 정책·관측 결과는 제외한다."""
     del write_policy_digest, served_model_attestation
+    specification = _canonical_model_spec(model_spec)
+    # 요금 미설정 실행의 기존 해시와 동일한 표현을 유지한다.
+    specification["pricing"] = None
+    return _digest_model_binding(specification, binding)
+
+
+def _digest_model_binding(specification: Mapping[str, Any], binding: HostModelBinding) -> str:
     canonical = {
-        "modelSpec": _canonical_model_spec(model_spec),
+        "modelSpec": specification,
         "binding": _binding_payload(binding),
     }
     encoded = json.dumps(

package/runtime/python/okstra_ctl/execution_manifest.py

@@ -559,7 +559,7 @@ def _validate_role_identity(
     role = _required_text(row, "role")
     provider = _required_text(row, "provider")
     model_id = _required_text(row, "modelId")
-    unknown = row.get("modelRef") is None or row.get("modelSpecDigest") is None
+    unknown = row.get("modelRef") is None
     if unknown and not _is_current_session_unknown_leader(payload, row, participant):
         raise ExecutionManifestError("unknown model is allowed only for current-session leader")
     if not unknown and row.get("binding") is None:
@@ -901,7 +901,11 @@ def _validate_next_attempt(manifest: ExecutionManifest, row: Attempt) -> None:
         raise ExecutionManifestError("previous attempt is not terminal")
     if last.status != "failed-no-mutation":
         raise ExecutionManifestError(
-            "invocation cannot append another attempt after a terminal mutation"
+            "invocation cannot append another attempt after a terminal mutation; "
+            "preserve the existing result and audit. Materialize a new corrective invocation "
+            "with okstra agent-prompt materialize, a new --invocation-id and distinct "
+            "--prompt/--result paths, retaining the same assignment and selected model. "
+            "Do not replay completed implementation."
         )