okstra 0.183.2 → 0.185.0

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 import argparse
 import importlib.util
 import json
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
 from datetime import datetime, timezone
 from pathlib import Path
 import sys
@@ -22,8 +22,21 @@ from .convergence import (
 )
 from .convergence_store import write_json_atomic
 from .json_boundary import JsonBoundaryError, load_owned_object
+from .report_finalize import task_manifest_path
 from .plan_derivations import extract_tokens, find_derivations
-from .plan_items import PlanItemContractError, extract_plan_items
+from .plan_items import (
+    NextDispatch,
+    PlanItemContractError,
+    advisory_plan_body_gating,
+    content_hash,
+    correction_prompt_text,
+    dispatch_item_ids,
+    extract_plan_items,
+    next_dispatch,
+    planning_stage_ledger,
+    reverify_item_ids,
+    tie_vote_item_ids,
+)
 from .paths import RunRef
 from .stage_ledger import build_stage_ledger
 from .claim_reproduction import NOT_RUNNABLE, reproduce
@@ -61,6 +74,64 @@ def _envelope(data: Mapping[str, Any]) -> dict[str, Any]:
     }
 
 
+def _merged_ledger(
+    planning: Mapping[str, Any],
+    run_manifest: Path | None,
+) -> dict[str, str]:
+    return planning_stage_ledger(planning, _stage_ledger_snapshot(run_manifest))
+
+
+def _previous_hashes(state_path: Path | None) -> dict[str, str]:
+    if state_path is None or not state_path.is_file():
+        return {}
+    rows = _state_plan_body_items(_load_json_object(state_path), state_path)
+    return {
+        str(row["id"]): str(row["verifiedContentHash"])
+        for row in rows
+        if isinstance(row, Mapping)
+        and isinstance(row.get("id"), str)
+        and isinstance(row.get("verifiedContentHash"), str)
+    }
+
+
+def _queue_for(
+    items: list[dict[str, Any]],
+    planning: Mapping[str, Any],
+    run_manifest: Path | None,
+    previous_hashes: Mapping[str, str] | None = None,
+    tied_ids: Sequence[str] | None = None,
+) -> list[str]:
+    ledger = _merged_ledger(planning, run_manifest)
+    if tied_ids is not None:
+        return tie_vote_item_ids(items, ledger, tied_ids)
+    if previous_hashes:
+        return reverify_item_ids(items, previous_hashes, ledger)
+    return dispatch_item_ids(items, ledger)
+
+
+def _queue_kwargs(args: argparse.Namespace) -> dict[str, Any]:
+    if getattr(args, "tie_vote", False):
+        state = getattr(args, "state", None)
+        if state is None:
+            raise PlanItemContractError("--tie-vote requires --state")
+        return {"tied_ids": _tied_ids(state)}
+    return {"previous_hashes": _previous_hashes(getattr(args, "state", None))}
+
+
+def _tied_ids(state_path: Path) -> list[str]:
+    if not state_path.is_file():
+        raise PlanItemContractError("--tie-vote requires --state with recorded verdicts")
+    items = _state_plan_body_items(_load_json_object(state_path), state_path)
+    gate = _gate_module()
+    return [
+        str(item["id"])
+        for item in items
+        if isinstance(item, Mapping)
+        and isinstance(item.get("id"), str)
+        and gate._is_unsettled_tie(dict(item))
+    ]
+
+
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="okstra plan-items",
@@ -76,11 +147,28 @@ def _parser() -> argparse.ArgumentParser:
     prepare = commands.add_parser("prepare")
     _add_plan_source(prepare)
     prepare.add_argument("--run-manifest", type=Path, required=True)
+    prepare.add_argument(
+        "--state", type=Path,
+        help="previous plan-body state; when it carries verifiedContentHash "
+             "rows the dispatch queue shrinks to the self-fix reverify set",
+    )
+    prepare.add_argument(
+        "--tie-vote", action="store_true",
+        help="dispatch queue is the needs-reverify ties in --state, nothing else",
+    )
     prompt = commands.add_parser("prompt")
     prompt.add_argument("--run-manifest", type=Path, required=True)
     validate_prepared = commands.add_parser("validate-prepared")
     _add_plan_source(validate_prepared)
     validate_prepared.add_argument("--run-manifest", type=Path, required=True)
+    validate_prepared.add_argument(
+        "--state", type=Path,
+        help="same previous state prepare used to shrink the dispatch queue",
+    )
+    validate_prepared.add_argument(
+        "--tie-vote", action="store_true",
+        help="same --tie-vote prepare used to shrink the dispatch queue",
+    )
     collect = commands.add_parser(
         "collect-verdicts",
         help="read this round's worker responses into a verdicts envelope",
@@ -138,6 +226,10 @@ def _parser() -> argparse.ArgumentParser:
         help="the verification round these verdicts were cast in; stamped on "
              "every row so a later self-fix can be told from a current judgement",
     )
+    apply_verdicts.add_argument(
+        "--append", action="store_true",
+        help="add these votes to existing rows instead of replacing the round",
+    )
     complete = commands.add_parser(
         "complete-round",
         help="derive and atomically record one verified plan-body round",
@@ -148,9 +240,26 @@ def _parser() -> argparse.ArgumentParser:
     complete.add_argument("--self-fix-note", action="append", default=[], metavar="<item-id>=<markdown-file>")
     complete.add_argument("--self-fix-group", action="append", default=[], metavar="<cause-file>=<item-id>[,<item-id>...]")
     complete.add_argument("--self-fix-stop-reason", choices=("all-resolved", "no-progress", "max-rounds-reached"))
+    _add_dispatch_commands(commands)
     return parser
 
 
+def _add_dispatch_commands(commands: Any) -> None:
+    nxt = commands.add_parser(
+        "next-dispatch",
+        help="decide whether this round opens a worker batch",
+    )
+    nxt.add_argument("--state", type=Path, required=True)
+    nxt.add_argument("--run-manifest", type=Path)
+    correction = commands.add_parser(
+        "correction-prompt",
+        help="environment-exception preamble then the assigned queue",
+    )
+    correction.add_argument("--state", type=Path, required=True)
+    correction.add_argument("--run-manifest", type=Path, required=True)
+    correction.add_argument("--worker", required=True)
+
+
 def _add_plan_source(parser: argparse.ArgumentParser) -> None:
     source = parser.add_mutually_exclusive_group(required=True)
     source.add_argument("--data", type=Path)
@@ -211,11 +320,43 @@ def _prepared_items_path(
     return path
 
 
+def _sync_task_manifest_gating(run_manifest: Path, gating: bool) -> None:
+    """준비 이후 매니페스트 ``gating`` 을 계획 사실로 맞춘다."""
+    try:
+        authority = validated_run_authority(run_manifest)
+        path = task_manifest_path(authority.project_root, authority.payload)
+        payload = load_owned_object(path, artifact="task manifest")
+    except (ConvergenceContractError, JsonBoundaryError, OSError, ValueError):
+        return
+    block = payload.get("convergence")
+    if not isinstance(block, dict):
+        return
+    pbv = block.get("planBodyVerification")
+    if not isinstance(pbv, dict):
+        return
+    pbv["gating"] = gating
+    write_json_atomic(path, payload)
+
+
 def _prepare(args: argparse.Namespace) -> dict[str, Any]:
     output = _prepared_items_path(args.run_manifest)
-    envelope = _envelope(_plan_source(args))
+    source = _plan_source(args)
+    envelope = _envelope(source)
+    envelope["dispatchQueue"] = _queue_for(
+        envelope["items"],
+        _planning(source),
+        args.run_manifest,
+        **_queue_kwargs(args),
+    )
+    gating = not advisory_plan_body_gating(_planning(source), envelope["items"])
+    _sync_task_manifest_gating(args.run_manifest, gating)
     write_json_atomic(output, envelope)
-    return {"ok": True, "operation": "prepare", "path": str(output)}
+    return {
+        "ok": True,
+        "operation": "prepare",
+        "path": str(output),
+        "gating": gating,
+    }
 
 
 _PAYLOAD_FIELDS = {
@@ -364,6 +505,13 @@ def _prompt(args: argparse.Namespace) -> str:
         _prepared_items_path(args.run_manifest, require_regular=True)
     )
     items = envelope.get("items") if isinstance(envelope.get("items"), list) else []
+    queue = envelope.get("dispatchQueue")
+    if isinstance(queue, list):
+        allowed = {item_id for item_id in queue if isinstance(item_id, str)}
+        items = [
+            item for item in items
+            if isinstance(item, Mapping) and item.get("id") in allowed
+        ]
     rows = ["# Plan verification queue\n", line("Item count", len(items))]
     for index, item in enumerate(items, 1):
         if not isinstance(item, Mapping):
@@ -376,10 +524,22 @@ def _prompt(args: argparse.Namespace) -> str:
 
 
 def _validate_prepared(args: argparse.Namespace) -> dict[str, Any]:
-    expected = _envelope(_plan_source(args))
+    source = _plan_source(args)
+    expected = _envelope(source)
     path = _prepared_items_path(args.run_manifest, require_regular=True)
-    if _load_json_object(path) != expected:
-        raise PlanItemContractError("prepared plan items do not match deterministic extraction")
+    actual = _load_json_object(path)
+    if actual.get("items") != expected["items"]:
+        raise PlanItemContractError(
+            "prepared plan items do not match deterministic extraction"
+        )
+    expected_queue = _queue_for(
+        expected["items"],
+        _planning(source),
+        args.run_manifest,
+        **_queue_kwargs(args),
+    )
+    if actual.get("dispatchQueue") != expected_queue:
+        raise PlanItemContractError("prepared dispatch queue does not match")
     return {"ok": True, "operation": "validate-prepared", "path": str(path)}
 
 
@@ -397,6 +557,9 @@ def _assigned_item_ids(items_path: Path) -> list[str]:
     items = envelope.get("items")
     if not isinstance(items, list):
         raise PlanItemContractError(f"items envelope has no `items` array: {items_path}")
+    queue = envelope.get("dispatchQueue")
+    if isinstance(queue, list):
+        return [item_id for item_id in queue if isinstance(item_id, str) and item_id]
     ids: list[str] = []
     for item in items:
         item_id = item.get("id") if isinstance(item, Mapping) else None
@@ -630,7 +793,9 @@ def _seed(args: argparse.Namespace) -> dict[str, Any]:
     already applied, `carriedForwardFromSeq`, `selfFixNote` — because a re-seed
     between rounds must not erase the round before it.
     """
-    extracted = _envelope(_plan_source(args))["items"]
+    source = _plan_source(args)
+    extracted = _envelope(source)["items"]
+    hashes = {item["id"]: content_hash(item) for item in extracted}
     if args.state is not None:
         data = _load_json_object(args.state) if args.state.is_file() else _new_v3_state()
         recorded = _state_plan_body_items(data, args.state)
@@ -661,11 +826,17 @@ def _seed(args: argparse.Namespace) -> dict[str, Any]:
             if item.get("stageScope") else {}
         ) | (
             {"block": item["block"]} if item.get("block") else {}
+        ) | (
+            {"contentHash": hashes[item["id"]]} if item["id"] in hashes else {}
         ) | {"verdicts": []}
         for item in extracted
         if item["id"] not in known
     ]
     recorded.extend(added)
+    for row in recorded:
+        item_id = row.get("id") if isinstance(row, Mapping) else None
+        if isinstance(item_id, str) and item_id in hashes:
+            row["contentHash"] = hashes[item_id]
     if args.state is not None:
         audit_rows = data.get("planItems")
         if not isinstance(audit_rows, list):
@@ -685,13 +856,26 @@ def _seed(args: argparse.Namespace) -> dict[str, Any]:
             for item in extracted
             if item["id"] not in audited
         )
-    ledger = _stage_ledger_snapshot(getattr(args, "run_manifest", None))
-    if ledger is not None:
-        verification = (
-            data["planBodyVerification"] if args.state is not None
-            else _planning(data)["planBodyVerification"]
-        )
+    verification = (
+        data["planBodyVerification"] if args.state is not None
+        else _planning(data)["planBodyVerification"]
+    )
+    ledger = _merged_ledger(_planning(source), getattr(args, "run_manifest", None))
+    if ledger:
         verification["stageLedger"] = ledger
+    previous = {
+        str(row["id"]): str(row["verifiedContentHash"])
+        for row in recorded
+        if isinstance(row, Mapping)
+        and isinstance(row.get("id"), str)
+        and isinstance(row.get("verifiedContentHash"), str)
+    }
+    verification["dispatchQueue"] = _queue_for(
+        extracted, _planning(source), getattr(args, "run_manifest", None), previous,
+    )
+    verification["gating"] = not advisory_plan_body_gating(
+        _planning(source), extracted,
+    )
     write_json_atomic(target, data)
     return {
         "ok": True,
@@ -743,7 +927,16 @@ def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
         else _plan_body_items(data, target)
     )
     known = {item.get("id") for item in recorded if isinstance(item, Mapping)}
-    rows = _incoming_verdict_rows(args, known)
+    verification = (
+        data["planBodyVerification"] if args.state is not None
+        else _planning(data)["planBodyVerification"]
+    )
+    queue = verification.get("dispatchQueue") if isinstance(verification, Mapping) else None
+    assigned = (
+        {item_id for item_id in queue if isinstance(item_id, str)}
+        if isinstance(queue, list) else known
+    )
+    rows = _incoming_verdict_rows(args, assigned)
     missing = sorted(item_id for item_id in rows if item_id not in known)
     if missing:
         raise PlanItemContractError(
@@ -754,25 +947,74 @@ def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
     if args.round_number < 1:
         raise PlanItemContractError("--round must be 1 or greater")
     project_root = _probe_project_root(getattr(args, "run_manifest", None))
+    writer = (
+        _append_item_verdicts if getattr(args, "append", False)
+        else _replace_item_verdicts
+    )
     for item in recorded:
         if isinstance(item, Mapping) and item.get("id") in rows:
-            # Overwrite, never merge: the contract records one round at a time,
-            # and a merged table lets a previous round's votes keep voting.
-            #
-            # Each row carries the round it was cast in. A self-fix round
-            # rewrites the plan *after* a verification round, so an item left out
-            # of a later round keeps a verdict on text that has since changed —
-            # invisibly, because the gate reads the table without knowing any
-            # row's vintage. Stamping it here is what lets the validator tell a
-            # current judgement from one two rewrites old.
-            item["verdicts"] = [
-                {**_judged_row(row, project_root), "round": args.round_number}
-                for row in rows[item["id"]]
-            ]
+            writer(item, rows[item["id"]], args.round_number, project_root)
     write_json_atomic(target, data)
     return {"ok": True, "operation": "apply-verdicts", "path": str(target)}
 
 
+def _stamped_verdicts(
+    incoming: list[dict[str, Any]], round_number: int, project_root: Path | None,
+) -> list[dict[str, Any]]:
+    return [
+        {**_judged_row(row, project_root), "round": round_number}
+        for row in incoming
+    ]
+
+
+def _remember_verified_hash(item: dict[str, Any]) -> None:
+    if item.get("contentHash"):
+        item["verifiedContentHash"] = item["contentHash"]
+
+
+def _replace_item_verdicts(
+    item: dict[str, Any],
+    incoming: list[dict[str, Any]],
+    round_number: int,
+    project_root: Path | None,
+) -> None:
+    item["verdicts"] = _stamped_verdicts(incoming, round_number, project_root)
+    _remember_verified_hash(item)
+
+
+def _append_item_verdicts(
+    item: dict[str, Any],
+    incoming: list[dict[str, Any]],
+    round_number: int,
+    project_root: Path | None,
+) -> None:
+    """동수 항목의 세 번째 표. 이미 투표한 워커는 거부한다."""
+    stamped = _stamped_verdicts(incoming, round_number, project_root)
+    existing = item.get("verdicts")
+    current = existing if isinstance(existing, list) else []
+    seen = {
+        row.get("worker") for row in current if isinstance(row, Mapping)
+    }
+    clash = [row.get("worker") for row in stamped if row.get("worker") in seen]
+    if clash:
+        raise PlanItemContractError(
+            f"plan item {item.get('id')} already has a vote from {clash} — "
+            "the extra vote must come from a worker who has not voted on it"
+        )
+    item["verdicts"] = [*current, *stamped]
+    _remember_verified_hash(item)
+
+
+def _gate_module() -> Any:
+    path = Path(__file__).parents[2] / "validators" / "validate-run.py"
+    spec = importlib.util.spec_from_file_location("okstra_plan_gate", path)
+    if spec is None or spec.loader is None:
+        raise PlanItemContractError("cannot load plan-body gate authority")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
 def _round_snapshot(item: Mapping[str, Any], round_number: int) -> dict[str, Any]:
     votes = {
         str(row["worker"]): str(row["verdict"])
@@ -852,7 +1094,15 @@ def _round_inputs(args: argparse.Namespace) -> tuple[dict[str, Any], list[dict[s
 
 
 def _round_snapshots(current: list[dict[str, Any]], verification: Mapping[str, Any], round_number: int) -> tuple[dict[str, dict[str, Any]], dict[str, Any]]:
-    snapshots = {str(item.get("id")): _round_snapshot(item, round_number) for item in current}
+    queue = verification.get("dispatchQueue")
+    scoped = current
+    if isinstance(queue, list):
+        allowed = {item_id for item_id in queue if isinstance(item_id, str)}
+        scoped = [
+            item for item in current
+            if isinstance(item, Mapping) and item.get("id") in allowed
+        ]
+    snapshots = {str(item.get("id")): _round_snapshot(item, round_number) for item in scoped}
     if not snapshots or any(not row["votes"] for row in snapshots.values()):
         raise PlanItemContractError("every current plan item needs a verdict before completion")
     summary = _plan_gate_summary(verification)
@@ -892,6 +1142,15 @@ def _complete_round(args: argparse.Namespace) -> dict[str, Any]:
         raise PlanItemContractError("--round must be 1 or greater")
     data, current, audit, history = _round_inputs(args)
     verification = data["planBodyVerification"]
+    if verification.get("gating") is False:
+        if args.round_number > 1:
+            raise PlanItemContractError(
+                "advisory plan-body gating allows one verification round"
+            )
+        if args.self_fix_group or args.self_fix_note:
+            raise PlanItemContractError(
+                "advisory plan-body gating forbids the self-fix loop"
+            )
     snapshots, summary = _round_snapshots(current, verification, args.round_number)
     _record_audit_round(audit, snapshots, args.round_number)
     gate = str(summary["recomputed"])
@@ -915,7 +1174,54 @@ def _complete_round(args: argparse.Namespace) -> dict[str, Any]:
     history[:] = [row for row in history if row.get("round") != args.round_number]
     history.append({"round": args.round_number, "completedAt": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), "gateResult": gate, "gateBlockedBy": verification["gateBlockedBy"]})
     write_json_atomic(args.state, data)
-    return {"ok": True, "operation": "complete-round", "path": str(args.state), "gateResult": gate}
+    payloads = _prepared_payloads(args.run_manifest)
+    return {
+        "ok": True,
+        "operation": "complete-round",
+        "path": str(args.state),
+        "gateResult": gate,
+        "nextDispatch": next_dispatch(current, payloads).as_dict(),
+    }
+
+
+def _prepared_payloads(run_manifest: Path | None) -> dict[str, dict[str, Any]]:
+    if run_manifest is None:
+        return {}
+    try:
+        envelope = _load_json_object(
+            _prepared_items_path(run_manifest, require_regular=True)
+        )
+    except PlanItemContractError:
+        return {}
+    items = envelope.get("items")
+    if not isinstance(items, list):
+        return {}
+    return {
+        str(item["id"]): item
+        for item in items
+        if isinstance(item, Mapping) and isinstance(item.get("id"), str)
+    }
+
+
+def _state_next_dispatch(args: argparse.Namespace) -> NextDispatch:
+    _data, current, _audit, _history = _round_inputs(args)
+    payloads = _prepared_payloads(getattr(args, "run_manifest", None))
+    return next_dispatch(current, payloads)
+
+
+def _next_dispatch(args: argparse.Namespace) -> dict[str, Any]:
+    decision = _state_next_dispatch(args)
+    return {"ok": True, "operation": "next-dispatch", **decision.as_dict()}
+
+
+def _correction_prompt(args: argparse.Namespace) -> str:
+    decision = _state_next_dispatch(args)
+    if decision.kind != "worker-correction" or args.worker not in decision.workers:
+        raise PlanItemContractError(
+            f"worker `{args.worker}` is not a blanket-UNVERIFIABLE correction "
+            "target — do not open a queue round"
+        )
+    return correction_prompt_text(_prompt(args))
 
 
 def _incoming_verdict_rows(
@@ -949,6 +1255,8 @@ _HANDLERS = {
     "seed": _seed,
     "apply-verdicts": _apply_verdicts,
     "complete-round": _complete_round,
+    "next-dispatch": _next_dispatch,
+    "correction-prompt": _correction_prompt,
 }
 
 
@@ -962,7 +1270,14 @@ def main(argv: list[str] | None = None) -> int:
     if isinstance(result, str):
         print(result, end="")
     elif args.command in {"prepare", "validate-prepared"}:
-        print("Plan items\n" + line("Status", "ready") + line("Operation", result["operation"]), end="")
+        rows = (
+            "Plan items\n"
+            + line("Status", "ready")
+            + line("Operation", result["operation"])
+        )
+        if "gating" in result:
+            rows += line("Gating", result["gating"])
+        print(rows, end="")
     else:
         print(json.dumps(result, ensure_ascii=False, indent=2))
     return 0

package/runtime/python/okstra_ctl/render.py

@@ -1584,6 +1584,10 @@ def _build_convergence_block(ctx: dict) -> dict:
       always emitted (dead-letter on other phases) so the schema stays stable.
       Its `selfFixMaxRounds` default 1 bounds the report-writer self-fix loop
       that runs before a planner-fixable defect is promoted to the user.
+      `gating` is true here because the plan does not exist yet. After the
+      report-writer draft, `okstra plan-items prepare` flips it to false when
+      `designPreparation.mode` is `no-design-inputs` and the Stage Map has
+      exactly one row.
 
     ctx knobs honoured:
     - `OKSTRA_PLAN_VERIFICATION`: "true" | "false" | "" (empty → default True).