okstra 0.220.1 → 0.222.0

package/runtime/python/okstra_ctl/convergence.py

@@ -5,6 +5,7 @@ import argparse
 from collections.abc import Mapping
 from dataclasses import dataclass
 import json
+import re
 from pathlib import Path, PurePosixPath
 import sys
 from typing import Any
@@ -54,9 +55,16 @@ from .convergence_migration import (
 from .convergence_provenance import (
     GROUPS_BASENAME_RE,
     discarded_worker_errors,
+    missing_scope_results,
     provenance_errors,
     worker_result_suffix,
 )
+from .correction_round import (
+    MAX_CORRECTION_ROUNDS,
+    CorrectionRoundError,
+    convergence_scope,
+    reverify_invocation_in_scope,
+)
 from .convergence_store import (
     load_acceptance_critic_batch,
     load_convergence_critic_batch,
@@ -152,6 +160,20 @@ def canonical_run_state_artifact(
     return expected
 
 
+def scoped_convergence_state(authority: RunArtifactAuthority, scope: str | None) -> Path:
+    """The final convergence state of one namespace: the manifest's own path, or a correction
+    round's `convergence-correction-r<N>-<task-type>-<seq>.json` beside it."""
+    initial = canonical_run_state_artifact(
+        authority, manifest_field="convergenceStatePath", prefix="convergence",
+        label="convergence state",
+    )
+    if scope is None:
+        return initial
+    return initial.parent / _canonical_run_artifact_name(
+        "convergence", authority.task_type, authority.state_sequence, scope
+    )
+
+
 def canonical_run_report_artifact(authority: RunArtifactAuthority) -> Path:
     report_sequence = _manifest_sequence(authority.payload, "reports")
     try:
@@ -335,7 +357,7 @@ _CLI_EPILOG = r"""Usage:
     --results <path>
   okstra convergence critic-prompt --run-manifest <path>
   okstra convergence reverify-prompt --run-manifest <path> --plan <path> \
-    --worker <worker-id>
+    --worker <worker-id> [--correction-round <N>]
   okstra convergence apply-critic-gaps --work-state <path> --results <path>
   okstra convergence census-audit --run-manifest <path> \
     --result <worker>=<path>... [--gapfill <worker>=<path>...]
@@ -349,6 +371,11 @@ _CLI_EPILOG = r"""Usage:
   okstra convergence example --kind <groups|round-results|critic-results|
     coverage-batch|acceptance-batch>
 
+Correction rounds (implementation): `prepare-groups`, `reverify-prompt` and
+`collect-results` take --correction-round <N> to converge round N's
+re-verification in its own namespace; `seed`, `plan-round`, `apply-round` and
+`finalize` read it from the `-correction-r<N>-` state paths they are given.
+
 Working lifecycle:
   groups v1.0/v2.0 → work v1.0/v2.0 → round-plan/results v1.0 → final v1.3
   historical final readers: v1.0, v1.1, v1.2
@@ -358,6 +385,12 @@ does not install or revive the obsolete okstra-convergence skill.
 """
 
 
+_CORRECTION_ROUND_HELP = (
+    "converge correction round N's re-verification in its own namespace "
+    "(`correction-r<N>` in every artifact name); omit for the initial round"
+)
+
+
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         epilog=_CLI_EPILOG,
@@ -407,6 +440,8 @@ def _parser() -> argparse.ArgumentParser:
     )
     prepare.add_argument("--run-manifest", type=Path, required=True)
     prepare.add_argument("--input", type=Path, required=True)
+    prepare.add_argument("--correction-round", type=int, metavar="<N>",
+                         help=_CORRECTION_ROUND_HELP)
 
     plan = subparsers.add_parser("plan-round", help="write the next dispatch plan")
     plan.add_argument("--work-state", type=Path, required=True)
@@ -426,6 +461,8 @@ def _parser() -> argparse.ArgumentParser:
                               "attempts, and a still-`started` attempt refuses "
                               "the collect until `okstra team await` closes it")
     collect.add_argument("--output", type=Path, required=True)
+    collect.add_argument("--correction-round", type=int, metavar="<N>",
+                         help=_CORRECTION_ROUND_HELP)
 
     apply = subparsers.add_parser("apply-round", help="apply structured round results")
     apply.add_argument("--work-state", type=Path, required=True)
@@ -464,6 +501,8 @@ def _parser() -> argparse.ArgumentParser:
     reverify_prompt.add_argument("--run-manifest", type=Path, required=True)
     reverify_prompt.add_argument("--plan", type=Path, required=True)
     reverify_prompt.add_argument("--worker", required=True)
+    reverify_prompt.add_argument("--correction-round", type=int, metavar="<N>",
+                                 help=_CORRECTION_ROUND_HELP)
 
     critic_verify_prompt = subparsers.add_parser(
         "critic-verify-prompt",
@@ -676,7 +715,8 @@ def _seeded_groups_provenance_errors(groups_path: Path, document: dict) -> list[
     file, and the same claims are re-checked at Phase 7 by `validate-run`,
     where a bad `itemId` surfaces hours later as a blocked approval.
     """
-    if GROUPS_BASENAME_RE.match(groups_path.name) is None:
+    match = GROUPS_BASENAME_RE.match(groups_path.name)
+    if match is None:
         return []
     run_dir = groups_path.parent.parent
     worker_results_dir = run_dir / "worker-results"
@@ -692,6 +732,7 @@ def _seeded_groups_provenance_errors(groups_path: Path, document: dict) -> list[
         worker_results_dir=worker_results_dir,
         suffix=suffix,
         groups_label=groups_path.name,
+        scope=match.group("scope"),
     )
 
 
@@ -701,12 +742,14 @@ def _seed_execution_manifest(
     manifest_path: Path | None,
     work_state_path: Path,
     final_state_path: Path,
-) -> ExecutionManifest | None:
+) -> tuple[ExecutionManifest | None, str | None]:
+    """The run's execution manifest and the convergence namespace the state paths name."""
     if manifest_path is None:
-        return None
+        return None, None
     manifest, authority = read_execution_manifest_view(manifest_path)
+    scope = None
     if grouped_input.get("schemaVersion") == "2.0":
-        _validate_v2_seed_authority(
+        scope = _validate_v2_seed_authority(
             groups_path,
             grouped_input,
             manifest_path,
@@ -715,7 +758,7 @@ def _seed_execution_manifest(
             final_state_path,
             execution_manifest=manifest,
         )
-    return manifest
+    return manifest, scope
 
 
 def _validate_v2_seed_authority(
@@ -727,7 +770,7 @@ def _validate_v2_seed_authority(
     final_state_path: Path,
     *,
     execution_manifest: ExecutionManifest,
-) -> None:
+) -> str | None:
     validated = _validated_v2_work_authority(
         work_state_path,
         grouped_input,
@@ -736,11 +779,12 @@ def _validate_v2_seed_authority(
     )
     if validated is None:
         raise ConvergenceContractError("v2 convergence groups require v2 work authority")
-    _manifest, run_dir, task_type, state_sequence = validated
+    _manifest, run_dir, task_type, state_sequence, scope = validated
     expected_groups_name = _canonical_run_artifact_name(
         "convergence-groups",
         task_type,
         state_sequence,
+        scope,
     )
     if groups_path.name != expected_groups_name:
         raise ConvergenceContractError(
@@ -760,7 +804,9 @@ def _validate_v2_seed_authority(
         state_sequence=state_sequence,
         prefix="convergence",
         label="state output",
+        scope=scope,
     )
+    return scope
 
 
 def _validated_v2_work_authority(
@@ -773,7 +819,7 @@ def _validated_v2_work_authority(
         Mapping[str, Any],
     ] | None = None,
     path_label: str = "working state",
-) -> tuple[ExecutionManifest, Path, str, str] | None:
+) -> tuple[ExecutionManifest, Path, str, str, str | None] | None:
     if state.get("schemaVersion") != "2.0":
         return None
     if state.get("executionIdentityVersion") != 2:
@@ -828,7 +874,7 @@ def _validated_v2_work_authority(
         manifest_path,
         canonical_run_ref,
     )
-    _validate_v2_state_artifact_path(
+    scope = _state_artifact_scope(
         work_state_path,
         state_dir=run_dir / "state",
         task_type=task_type,
@@ -836,7 +882,7 @@ def _validated_v2_work_authority(
         prefix="convergence-work",
         label=path_label,
     )
-    return execution_manifest, run_dir, task_type, state_sequence
+    return execution_manifest, run_dir, task_type, state_sequence, scope
 
 
 def _project_root_for_v2_work_state(
@@ -944,6 +990,7 @@ def _canonical_run_artifact_name(
     prefix: str,
     task_type: str,
     sequence: str,
+    scope: str | None = None,
 ) -> str:
     try:
         sequence_number = int(sequence)
@@ -967,7 +1014,7 @@ def _canonical_run_artifact_name(
             "run manifest sequence is not canonical"
         )
     suffix = probe.removeprefix("run-manifest").removesuffix(".json")
-    return f"{prefix}{suffix}.json"
+    return f"{prefix}{'-' + scope if scope else ''}{suffix}.json"
 
 
 def _manifest_run_directory(
@@ -1007,11 +1054,13 @@ def _validate_v2_state_artifact_path(
     state_sequence: str,
     prefix: str,
     label: str,
+    scope: str | None = None,
 ) -> None:
     expected_path = state_dir / _canonical_run_artifact_name(
         prefix,
         task_type,
         state_sequence,
+        scope,
     )
     if (
         supplied_path.absolute() != supplied_path.resolve()
@@ -1022,6 +1071,28 @@ def _validate_v2_state_artifact_path(
         )
 
 
+def _state_artifact_scope(
+    supplied_path: Path,
+    *,
+    state_dir: Path,
+    task_type: str,
+    state_sequence: str,
+    prefix: str,
+    label: str,
+) -> str | None:
+    """The namespace a canonical state path names: the initial one or a correction round's."""
+    scopes = [None, *(convergence_scope(n) for n in range(1, MAX_CORRECTION_ROUNDS + 1))]
+    for scope in scopes:
+        name = _canonical_run_artifact_name(prefix, task_type, state_sequence, scope)
+        if supplied_path.name == name:
+            _validate_v2_state_artifact_path(
+                supplied_path, state_dir=state_dir, task_type=task_type,
+                state_sequence=state_sequence, prefix=prefix, label=label, scope=scope,
+            )
+            return scope
+    raise ConvergenceContractError(f"{label} path does not match run authority")
+
+
 def _manifest_project_root(authority: dict[str, Any]) -> Path:
     value = authority.get("projectRoot")
     if not isinstance(value, str) or not value.strip():
@@ -1075,7 +1146,7 @@ def _canonical_project_artifact_path(
 
 def _seed(args: argparse.Namespace) -> tuple[str, Path]:
     grouped_input = load_owned_json_object(args.groups)
-    execution_manifest = _seed_execution_manifest(
+    execution_manifest, scope = _seed_execution_manifest(
         args.groups,
         grouped_input,
         args.run_manifest,
@@ -1087,7 +1158,10 @@ def _seed(args: argparse.Namespace) -> tuple[str, Path]:
         raise ConvergenceContractError(
             "grouping cites source items no worker reported: " + "; ".join(provenance)
         )
-    discarded = discarded_worker_errors(grouped_input, execution_manifest)
+    unconverged = missing_scope_results(grouped_input, execution_manifest, scope)
+    if unconverged:
+        raise ConvergenceContractError("; ".join(unconverged))
+    discarded = discarded_worker_errors(grouped_input, execution_manifest, scope)
     if discarded:
         raise ConvergenceContractError(
             "grouping cites workers whose result was discarded: " + "; ".join(discarded)
@@ -1134,6 +1208,7 @@ def _plan_round(
     if errors:
         raise ConvergenceContractError("invalid working state: " + "; ".join(errors))
     plan = plan_next_round(state)
+    _refuse_dispatched_plan_overwrite(args.work_state, state, args.plan, plan)
     write_json_atomic(args.plan, plan)
     # 리드의 `phase-5.5-convergence round=<N> queue=<count>` 줄이 이 두 값을 그대로
     # 옮긴다. 리드가 계획 파일을 세면 `queueFindingIds` 와 혼동해 queue=0 을 적었다.
@@ -1143,6 +1218,46 @@ def _plan_round(
     }
 
 
+_PLAN_SCOPE_RE = re.compile(r"-plan-(correction-r[1-9][0-9]*)-")
+
+
+def _refuse_dispatched_plan_overwrite(
+    work_state_path: Path, state: Mapping[str, Any], plan_path: Path, plan: Mapping[str, Any],
+) -> None:
+    """A dispatched round plan is the assignment record its reverify votes are collected against.
+
+    Overwriting it with a different plan (dev-11378: a round-1 dispatch plan replaced by a
+    finalize plan of another convergence) leaves those votes with no plan to match.
+    """
+    if not plan_path.is_file():
+        return
+    existing = load_owned_json_object(plan_path)
+    if existing == plan or existing.get("action") != "dispatch":
+        return
+    authority = _validated_v2_work_authority(work_state_path, state)
+    if authority is None:
+        return
+    manifest = authority[0]
+    round_number = existing.get("round")
+    if not isinstance(round_number, int):
+        return
+    # 덮어쓰려는 계획의 범위는 새 계획이 아니라 그 파일 이름이 정한다.
+    named = _PLAN_SCOPE_RE.search(plan_path.name)
+    scope = named.group(1) if named else None
+    dispatched = sorted(
+        invocation.invocation_ref for invocation in manifest.invocations
+        if invocation.dispatch_kind == f"reverify-r{round_number}"
+        and reverify_invocation_in_scope(invocation.invocation_ref, scope, round_number)
+    )
+    if dispatched:
+        raise ConvergenceContractError(
+            f"{plan_path.name} is round {round_number}'s dispatched plan "
+            f"({', '.join(dispatched)}); write the new plan to another path — a "
+            "correction round's re-convergence names its plans "
+            "`convergence-round-<k>-plan-correction-r<N>-<task-type>-<seq>.json`"
+        )
+
+
 def _apply_round(args: argparse.Namespace) -> tuple[str, Path]:
     state = load_owned_json_object(args.work_state)
     _validated_v2_work_authority(args.work_state, state)
@@ -1178,7 +1293,7 @@ def _finalize(args: argparse.Namespace) -> tuple[str, Path]:
     state = load_owned_json_object(args.work_state)
     authority = _validated_v2_work_authority(args.work_state, state)
     if authority is not None:
-        _manifest, run_dir, task_type, state_sequence = authority
+        _manifest, run_dir, task_type, state_sequence, scope = authority
         _validate_v2_state_artifact_path(
             args.output,
             state_dir=run_dir / "state",
@@ -1186,6 +1301,7 @@ def _finalize(args: argparse.Namespace) -> tuple[str, Path]:
             state_sequence=state_sequence,
             prefix="convergence",
             label="final state",
+            scope=scope,
         )
     final = finalize_working_state(state)
     migration = state.get("migration")
@@ -1301,6 +1417,7 @@ def _dispatch_rows_from_manifest(
     plan: Mapping[str, Any],
     manifest: Any,
     run_manifest_path: Path,
+    scope: str | None = None,
 ) -> list[dict[str, Any]]:
     """`dispatches[]` 를 execution manifest 의 attempt 원장에서 도출한다.
 
@@ -1338,6 +1455,7 @@ def _dispatch_rows_from_manifest(
         matches = [
             invocation for invocation in getattr(manifest, "invocations", ())
             if invocation.dispatch_kind == kind
+            and reverify_invocation_in_scope(invocation.invocation_ref, scope, round_number)
             and (
                 source_roles.get(invocation.role_execution_ref) == role_ref
                 if isinstance(role_ref, str) and role_ref
@@ -1432,7 +1550,11 @@ def _collect_results(args: argparse.Namespace) -> tuple[str, Path]:
             "collect-results reads dispatch outcomes from a v2 execution manifest; "
             "a legacy v1 roster has no attempt ledger to read"
         )
-    dispatches = _dispatch_rows_from_manifest(plan, manifest, args.run_manifest)
+    try:
+        scope = convergence_scope(args.correction_round)
+    except CorrectionRoundError as exc:
+        raise ConvergenceContractError(str(exc)) from exc
+    dispatches = _dispatch_rows_from_manifest(plan, manifest, args.run_manifest, scope)
     votes = _worker_votes(args.result, planned)
     returned_without_completion = sorted(
         worker for worker in votes
@@ -1700,6 +1822,18 @@ def _critic_prompt(args: argparse.Namespace) -> str:
     )
 
 
+def _correction_scope(
+    args: argparse.Namespace, authority: RunArtifactAuthority,
+) -> str | None:
+    round_number = getattr(args, "correction_round", None)
+    if round_number is not None and authority.task_type != "implementation":
+        raise ConvergenceContractError("correction rounds exist only in implementation runs")
+    try:
+        return convergence_scope(round_number)
+    except CorrectionRoundError as exc:
+        raise ConvergenceContractError(str(exc)) from exc
+
+
 def _prepare_groups(args: argparse.Namespace) -> tuple[str, Path]:
     authority = validated_run_authority(args.run_manifest)
     manifest = authority.payload
@@ -1708,7 +1842,8 @@ def _prepare_groups(args: argparse.Namespace) -> tuple[str, Path]:
         source["worker"] for group in groups for source in group["sourceItems"]
     ))
     output = authority.run_dir / "state" / _canonical_run_artifact_name(
-        "convergence-groups", authority.task_type, authority.state_sequence
+        "convergence-groups", authority.task_type, authority.state_sequence,
+        _correction_scope(args, authority),
     )
     config = _convergence_config(authority)
     workers = [_group_worker(manifest, worker) for worker in worker_ids]
@@ -1741,8 +1876,9 @@ def _prepare_groups(args: argparse.Namespace) -> tuple[str, Path]:
 def _reverify_prompt(args: argparse.Namespace) -> str:
     """한 워커의 reverify 지시문 본문. 입력은 매니페스트·라운드 계획·워커 id."""
     authority = validated_run_authority(args.run_manifest)
+    scope = _correction_scope(args, authority)
     groups_path = authority.run_dir / "state" / _canonical_run_artifact_name(
-        "convergence-groups", authority.task_type, authority.state_sequence
+        "convergence-groups", authority.task_type, authority.state_sequence, scope
     )
     if not groups_path.is_file():
         raise ConvergenceContractError(
@@ -1764,7 +1900,7 @@ def _reverify_prompt(args: argparse.Namespace) -> str:
         round_number=round_number,
         findings=reverify_findings(
             groups, plan, args.worker,
-            project_root=authority.project_root, run_dir=authority.run_dir,
+            project_root=authority.project_root, run_dir=authority.run_dir, scope=scope,
         ),
     )
 

package/runtime/python/okstra_ctl/convergence_critic_prompt.py

@@ -129,10 +129,11 @@ def analyser_results(
     *,
     project_root: Path,
     run_dir: Path,
+    scope: str | None = None,
 ) -> list[AnalyserResult]:
     """분석 audience 워커마다 결과 파일 경로와 finding id 를 짝지어 돌려준다.
 
-    출처 검사와 같은 실행 원장을 사용해야 교정 전 결과를 재검증하지 않는다.
+    출처 검사와 같은 실행 원장·수렴 범위를 사용해야 grouping 이 인용한 결과를 재검증한다.
     """
     suffix = worker_result_suffix(Path(run_dir), groups)
     if suffix is None:
@@ -140,7 +141,7 @@ def analyser_results(
             "cannot resolve the worker-result suffix from the grouping's "
             "runManifestPath"
         )
-    paths = worker_result_paths(Path(run_dir), groups, suffix)
+    paths = worker_result_paths(Path(run_dir), groups, suffix, scope)
     by_worker = _findings_by_worker(groups)
     return [
         AnalyserResult(

package/runtime/python/okstra_ctl/convergence_migration.py

@@ -45,6 +45,16 @@ def decide_seed_action(
     task_key = grouped_input.get("taskKey")
     digest = grouped_input_digest(grouped_input)
     final_status, final_value = _inspect_final(final_state_path)
+    work_status, work_value = _inspect_work(work_state_path)
+    if restart_from_round0 and work_status != "invalid":
+        # 되살릴 무효 상태가 없는데 재시작을 요청받으면 조용히 재사용·재개하던 것이
+        # 정정 라운드 재수렴을 초기 final 재사용으로 끝냈다(dev-11378).
+        raise ConvergenceContractError(
+            "--restart-from-round0 recovers an invalid working state, and this working "
+            f"state is {work_status}; to converge a correction round's re-verification, "
+            "prepare its own namespace with `okstra convergence prepare-groups "
+            "--correction-round <N>` and seed those paths"
+        )
     if final_status == "terminal":
         assert final_value is not None
         version = final_value.get("schemaVersion")
@@ -55,7 +65,6 @@ def decide_seed_action(
         )
         return SeedDecision("reuse-final", None, None, reason)
 
-    work_status, work_value = _inspect_work(work_state_path)
     invalid_final = final_status == "invalid"
     if work_status == "valid":
         assert work_value is not None