okstra 0.186.7 → 0.188.0

package/runtime/python/okstra_ctl/agent/prompt_cli/results.py

@@ -0,0 +1,197 @@
+"""찍어 낸 명세와 워커가 낸 결과를 잇는다.
+
+materialize 가 만든 명세에 대해, 이 층은 그 뒤에 오는 것들을 다룬다 — 디스패치
+기록, 결과 링크, 거절, 완료 표시, 검증. 전부 이미 존재하는 명세를 전제하고,
+새 명세를 만들지 않는다.
+"""
+from __future__ import annotations
+
+import argparse
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ..invocation import (
+    AgentModelAssignment,
+    agent_model_assignment_from_payload,
+    materialize_standalone_result,
+    publish_standalone_completion,
+    verify_standalone_completion,
+    verify_agent_invocation,
+)
+from ...dispatch_state import (
+    link_agent_dispatch_result,
+    record_verified_agent_dispatch,
+    abandon_agent_dispatch_attempt,
+    reject_agent_dispatch_result,
+)
+from .emit import _emit
+from .inputs import (
+    AgentPromptCliError,
+    _is_relative_to,
+    _mapping,
+    _project_input,
+    _project_root,
+    _read_json_object,
+)
+
+
+def _record_dispatch(args: argparse.Namespace) -> None:
+    project_root = _project_root(args.project_root)
+    record = record_verified_agent_dispatch(
+        project_root=project_root,
+        run_manifest_path=_project_input(
+            project_root, args.run_manifest, "run manifest"
+        ),
+        metadata_path=_project_input(
+            project_root, args.metadata, "agent invocation metadata"
+        ),
+        enforcement_mode=args.enforcement_mode,
+    )
+    _emit(record, args.json)
+
+
+def _reject_result(args: argparse.Namespace) -> None:
+    project_root = _project_root(args.project_root)
+    row = reject_agent_dispatch_result(
+        project_root=project_root,
+        run_manifest_path=_project_input(
+            project_root, args.run_manifest, "run manifest"
+        ),
+        dispatch_id=args.dispatch_id,
+        superseded_by=args.superseded_by,
+        reason=args.reason,
+    )
+    _emit(row, args.json)
+
+
+def _abandon_attempt(args: argparse.Namespace) -> None:
+    project_root = _project_root(args.project_root)
+    row = abandon_agent_dispatch_attempt(
+        project_root=project_root,
+        run_manifest_path=_project_input(
+            project_root, args.run_manifest, "run manifest"
+        ),
+        invocation_ref=args.invocation_ref,
+        reason=args.reason,
+    )
+    _emit(row, args.json)
+
+
+def _link_result(args: argparse.Namespace) -> None:
+    project_root = _project_root(args.project_root)
+    link = link_agent_dispatch_result(
+        project_root=project_root,
+        run_manifest_path=_project_input(
+            project_root, args.run_manifest, "run manifest"
+        ),
+        dispatch_id=args.dispatch_id,
+        result_path=_project_input(project_root, args.result, "agent result"),
+    )
+    _emit(link, args.json)
+
+
+def _verify(args: argparse.Namespace) -> None:
+    project_root = _project_root(args.project_root)
+    metadata_path = _project_input(project_root, args.metadata, "metadata")
+    metadata = _read_json_object(metadata_path, "metadata")
+    contract_source = _mapping(metadata.get("contractSource"), "contract source")
+    mode = contract_source.get("mode")
+    expected_manifest: Path | None = None
+    expected_assignment: AgentModelAssignment | None = None
+    if mode == "run":
+        if not args.run_manifest:
+            raise AgentPromptCliError("run invocation verification requires --run-manifest")
+        expected_manifest = _project_input(project_root, args.run_manifest, "run manifest")
+        manifest = _read_json_object(expected_manifest, "run manifest")
+        assignments = _mapping(manifest.get("invocationAssignments"), "run assignments")
+        reference = metadata.get("assignmentRef")
+        if not isinstance(reference, str) or reference not in assignments:
+            raise AgentPromptCliError("assignment reference is missing from run manifest")
+        expected_assignment = agent_model_assignment_from_payload(assignments[reference])
+    elif mode == "standalone":
+        if args.run_manifest:
+            raise AgentPromptCliError("standalone invocation verification forbids --run-manifest")
+    else:
+        raise AgentPromptCliError("contract source mode is invalid")
+    errors = verify_agent_invocation(
+        metadata_path,
+        project_root=project_root,
+        expected_run_manifest_path=expected_manifest,
+        expected_assignment=expected_assignment,
+    )
+    if errors:
+        raise AgentPromptCliError("; ".join(errors))
+
+
+def _materialize_result(args: argparse.Namespace) -> None:
+    project_root = _project_root(args.project_root)
+    metadata_path = _project_input(project_root, args.metadata, "metadata")
+    root = project_root / ".okstra" / "agent-invocations" / args.purpose
+    temporary_root = root / ".tmp"
+    returned_body_path = _project_input(
+        project_root,
+        args.returned_body_file,
+        "returned body",
+    )
+    if not temporary_root.is_dir() or not _is_relative_to(
+        returned_body_path,
+        temporary_root.resolve(strict=True),
+    ):
+        raise AgentPromptCliError(
+            "returned body file must be inside the standalone purpose .tmp directory"
+        )
+    result = materialize_standalone_result(
+        project_root=project_root,
+        purpose=args.purpose,
+        metadata_path=metadata_path,
+        returned_body=returned_body_path.read_bytes(),
+    )
+    _emit({
+        "ok": True,
+        "purpose": result.purpose,
+        "invocationId": result.invocation_id,
+        "metadataPath": str(result.prompt_metadata_path),
+        "resultPath": str(result.result_path),
+        "resultEnvelopeDigest": result.result_envelope_digest,
+    }, args.json)
+
+
+def _complete(args: argparse.Namespace) -> None:
+    project_root = _project_root(args.project_root)
+    metadata_path = _project_input(project_root, args.metadata, "metadata")
+    completion = publish_standalone_completion(
+        project_root=project_root,
+        purpose=args.purpose,
+        metadata_path=metadata_path,
+        completed_at=datetime.now(timezone.utc),
+    )
+    _emit({
+        "ok": True,
+        "purpose": args.purpose,
+        "metadataPath": str(metadata_path),
+        "completionPath": str(completion),
+    }, args.json)
+
+
+def _verify_completion(args: argparse.Namespace) -> None:
+    project_root = _project_root(args.project_root)
+    completion_path = _project_input(
+        project_root,
+        args.completion,
+        "completion",
+    )
+    verified = verify_standalone_completion(
+        completion_path,
+        project_root=project_root,
+        expected_purpose=args.purpose,
+    )
+    _emit({
+        "ok": True,
+        "purpose": verified.purpose,
+        "invocationId": verified.invocation_id,
+        "metadataPath": str(verified.prompt_metadata_path),
+        "resultPath": str(verified.result_path),
+        "completionPath": str(verified.completion_path),
+        "resultEnvelopeDigest": verified.result_envelope_digest,
+        "returnedBody": verified.returned_body,
+    }, args.json)

package/runtime/python/okstra_ctl/agent/prompt_cli/run_identity.py

@@ -0,0 +1,107 @@
+"""materialize 를 요청한 신원이 이 run 이 발급한 것인지 확인한다.
+
+run manifest 는 어떤 role 이 어떤 assignment 로 실행되는지를 이미 적어 두었다.
+CLI 인자가 그것과 어긋나면 감사 기록이 실행과 달라지므로 거절한다. 이 검사가
+없으면 매니페스트에 없는 role 로 프롬프트를 찍어 낼 수 있다.
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from ...worker_prompt_policy import (
+    CRITIC_DUTY_BY_ASSIGNMENT_SEGMENT,
+    resolve_prompt_plan_for_manifest,
+)
+from .inputs import AgentPromptCliError
+
+
+def _validate_run_identity(
+    manifest: Mapping[str, Any],
+    *,
+    worker_id: str,
+    dispatch_kind: str,
+    assignment_ref: str,
+    audience: str,
+) -> None:
+    expected: str
+    if assignment_ref == "lead":
+        expected = "lead"
+        if worker_id != "lead":
+            raise AgentPromptCliError("lead assignment requires worker ID 'lead'")
+    elif assignment_ref == "translator":
+        expected = "translator"
+        if worker_id != "translator":
+            raise AgentPromptCliError("translator assignment requires worker ID 'translator'")
+    elif assignment_ref.startswith("critic/"):
+        scope = assignment_ref.split("/", 1)[1]
+        expected = CRITIC_DUTY_BY_ASSIGNMENT_SEGMENT.get(scope, "")
+        if not expected or dispatch_kind != "critic":
+            raise AgentPromptCliError("critic assignment identity is invalid")
+        # provider 대조는 여기 두지 않는다. critic 의 `worker_id` 는 배정 참조의
+        # 마지막 마디(`scope` / `acceptance`)이고 provider 이름이 아니다
+        # (`render.py` 의 로스터 행이 `assignment_ref.rsplit("/", 1)[-1]` 로 만든다).
+        # 종전에 있던 `provider != worker_id` 검사는 두 어휘를 비교해서 늘 참이 되는
+        # 형태였고, 설정을 run manifest 에서 찾다 못 찾아 조용히 건너뛰었기에
+        # 드러나지 않았다. 정본에서 읽게 고치면 모든 critic 디스패치가 거부된다.
+    else:
+        try:
+            expected = resolve_prompt_plan_for_manifest(
+                manifest=manifest,
+                worker_id=worker_id,
+                dispatch_kind=dispatch_kind,
+            ).duty_audience
+        except ValueError as exc:
+            raise AgentPromptCliError(str(exc)) from exc
+        if audience != expected and _manifest_issued_role_execution(
+            manifest, audience=audience, assignment_ref=assignment_ref
+        ):
+            # The prompt plan names a worker's role by worker id, so on an
+            # implementation run the executor's provider resolves to the
+            # executor role no matter which role execution is being targeted.
+            # But the manifest issues one role execution per role, and a
+            # provider serving as both executor and verifier gets two — a
+            # normal roster, since the verifier contract accepts reusing the
+            # executor's model behind its own session. Refusing the second
+            # audience made a role execution okstra had itself issued
+            # undispatchable, which costs the run an independent verifier.
+            expected = audience
+    if audience != expected:
+        raise AgentPromptCliError(
+            f"audience {audience!r} does not match required audience {expected!r}"
+        )
+
+
+def _manifest_issued_role_execution(
+    manifest: Mapping[str, Any],
+    *,
+    audience: str,
+    assignment_ref: str,
+) -> bool:
+    """Whether this run issued a role execution for that audience's role.
+
+    Keyed on the manifest's own rows, not on what the prompt plan infers from
+    a worker id: the question is whether okstra created the execution being
+    targeted, and only the manifest answers that.
+    """
+    from ...domain.role import RoleCatalogError, role_for_duty
+
+    try:
+        role = role_for_duty(audience)
+    except RoleCatalogError:
+        return False
+    assignments = manifest.get("invocationAssignments")
+    assignment = (
+        assignments.get(assignment_ref) if isinstance(assignments, Mapping) else None
+    )
+    provider = (
+        assignment.get("provider") if isinstance(assignment, Mapping) else None
+    )
+    if not provider:
+        return False
+    executions = manifest.get("roleExecutions")
+    return any(
+        isinstance(row, Mapping)
+        and row.get("role") == role
+        and row.get("provider") == provider
+        for row in (executions if isinstance(executions, list) else [])
+    )

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -67,7 +67,7 @@ WORKER_PROFILE_SECTIONS_BY_TASK_TYPE = {
         "Brief consumption",
         "Worker planning procedure",
         "Pre-planning context exploration",
-        "Design principles applied when scoring options",
+        "Design principles applied to realization review",
     ),
     "final-verification": (
         "Worker verification procedure",
@@ -102,8 +102,17 @@ def build_analysis_packet(
     fix_history_text: str = "",
     stage_ledger_json: str = "",
     stage_ledger_notice: str = "",
+    prior_planning_summary: str = "",
 ) -> str:
-    """Return the primary compact input for Claude/Codex/Antigravity analysers."""
+    """Return the primary compact input for Claude/Codex/Antigravity analysers.
+
+    `fix_history_text`, `stage_ledger_json` / `stage_ledger_notice`, and
+    `prior_planning_summary` are pre-rendered by their own modules
+    (`fix_cycles`, `stage_ledger`, `prior_planning`) because each is assembled
+    from disk state this file does not own. Each arrives already narrowed, and
+    an empty string means the caller found nothing to carry — the matching
+    block is then omitted rather than rendered saying "none".
+    """
     brief_text = task_brief_path.read_text(encoding="utf-8")
     profile_text = analysis_profile_path.read_text(encoding="utf-8")
     reference_text = _read_optional(reference_expectations_path)
@@ -126,6 +135,7 @@ def build_analysis_packet(
     parts.extend(_fix_history_block(fix_history_text))
     parts.extend(_stage_ledger_block(stage_ledger_json))
     parts.extend(_stage_ledger_unavailable_block(stage_ledger_notice))
+    parts.extend(_prior_planning_block(prior_planning_summary))
     parts.extend(_clarification_block(clarification_text))
     parts.extend(_directive_block(directive))
     body = "\n".join(part.rstrip() for part in parts).rstrip() + "\n"
@@ -334,8 +344,11 @@ def _stage_ledger_block(stage_ledger_json: str) -> list[str]:
         "authority is the latter.",
         "",
         "A `planDivergence` entry means the two plans disagree about a",
-        "completed stage. Treat it as a blocker for any new stage number and",
-        "report it; do not resolve it by choosing one of the two yourself.",
+        "completed stage, or that the plan the completed stages were built",
+        "against could not be read so that comparison never ran. Treat either",
+        "as a blocker for any new stage number and report it; do not resolve",
+        "it by choosing one of the two yourself. Completed stages built",
+        "against an earlier plan are not a divergence.",
         "",
         "```json",
         stage_ledger_json.strip(),
@@ -371,6 +384,36 @@ def _stage_ledger_unavailable_block(notice: str) -> list[str]:
     ]
 
 
+def _prior_planning_block(prior_planning_summary: str) -> list[str]:
+    """직전 계획 run 의 맥락. 직전 run 이 없으면 블록 자체가 없다.
+
+    머리글이 이 블록의 용도를 스스로 말한다. 그러지 않으면 워커는 표에 실린
+    계획을 승인된 것으로 읽고 그대로 옮겨 적는다 — 이 블록이 실리는 run 은
+    직전 계획이 **승인에 도달하지 못해** 다시 도는 run 이므로 그 독해는 틀렸다.
+    """
+    if not prior_planning_summary.strip():
+        return []
+    return [
+        "",
+        "## Prior Planning Run",
+        "",
+        "What this task's previous implementation-planning run recorded. It is",
+        "here so that stages the previous plan already settled stay textually",
+        "stable across the re-run, and so settled analysis is not derived from",
+        "the brief a second time under new `P-*` numbers.",
+        "",
+        "It is NOT an approved plan and NOT an instruction to copy. The",
+        "previous run did not reach approval — that is why this run exists —",
+        "so every line below is still open to revision. Where the brief, the",
+        "directive, or a clarification answer disagrees with it, they win, and",
+        "a stage you are changing is rewritten rather than carried. Read the",
+        "report at the path below for anything this summary leaves out.",
+        "",
+        prior_planning_summary.strip(),
+        "",
+    ]
+
+
 def _clarification_block(clarification_text: str) -> list[str]:
     if not clarification_text.strip():
         return []