okstra 0.223.2 → 0.224.0

package/runtime/python/okstra_ctl/plan_item_evidence.py

@@ -0,0 +1,237 @@
+"""Conservative evidence snapshots for plan-verification verdict reuse."""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import stat
+from collections.abc import Mapping, Sequence
+from copy import deepcopy
+from pathlib import Path
+from typing import Any, TypedDict
+
+from .plan_items import content_hash, is_critic_worker
+from .paths import find_asset_root
+from .report_narrative import writer_owned_data
+
+
+class FileSnapshot(TypedDict):
+    path: str
+    hash: str
+    mode: int | None
+
+
+class ReviewInputs(TypedDict):
+    version: int
+    items: dict[str, dict[str, Any]]
+    files: dict[str, FileSnapshot | None]
+    dependencies: dict[str, list[dict[str, Any]]]
+    workers: list[str]
+    context: str
+    complete: bool
+    planContext: dict[str, Any]
+    priorReviewHashes: dict[str, str]
+
+
+def _digest(value: object) -> str:
+    return hashlib.sha256(
+        json.dumps(value, sort_keys=True, ensure_ascii=False).encode("utf-8")
+    ).hexdigest()
+
+
+def _file_snapshot(root: Path, name: str) -> FileSnapshot | None:
+    path = root / name
+    try:
+        resolved = path.resolve(strict=False)
+        if not resolved.is_relative_to(root.resolve()):
+            return None
+        before = path.stat()
+        if stat.S_ISREG(before.st_mode):
+            digest = hashlib.sha256(path.read_bytes()).hexdigest()
+            after = path.stat()
+            changed = any(getattr(before, field) != getattr(after, field) for field in (
+                "st_dev", "st_ino", "st_size", "st_mtime_ns", "st_ctime_ns", "st_mode",
+            ))
+            if changed or resolved != path.resolve(strict=False):
+                return None
+            return {"path": str(resolved), "hash": digest, "mode": stat.S_IMODE(before.st_mode)}
+    except FileNotFoundError:
+        if not path.is_symlink():
+            return {"path": str(path.resolve(strict=False)), "hash": "absent", "mode": None}
+    except (OSError, RuntimeError):
+        return None
+    return None
+
+
+def _payload_paths(value: object) -> set[str]:
+    if isinstance(value, str):
+        return {value} if value and not any(c in value for c in "\n`*") else set()
+    if isinstance(value, list):
+        return set().union(*(_payload_paths(entry) for entry in value))
+    if isinstance(value, Mapping):
+        return _payload_paths(value.get("path"))
+    return set()
+
+
+def capture_review_inputs(
+    items: Sequence[Mapping[str, Any]],
+    planning: Mapping[str, Any],
+    manifest: Mapping[str, Any],
+    root: Path,
+    previous_rows: Sequence[Mapping[str, Any]] = (),
+) -> ReviewInputs:
+    paths: set[str] = set()
+    for item in items:
+        payload = item.get("payload") or {}
+        paths.update(
+            match for match in re.findall(r"`([^`\s]+)`", json.dumps(payload))
+            if "/" in match or "." in match
+        )
+        for field in ("files", "plannedPaths"):
+            paths.update(_payload_paths(payload.get(field)))
+    for row in previous_rows:
+        for vote in row.get("verdicts", []):
+            dependencies = vote.get("dependencies")
+            if isinstance(dependencies, Mapping) and isinstance(dependencies.get("paths"), list):
+                paths.update(p for p in dependencies.get("paths", []) if isinstance(p, str))
+    packet = manifest.get("analysisPacketPath")
+    if isinstance(packet, str) and packet:
+        paths.add(packet)
+    metadata = writer_owned_data({"implementationPlanning": planning})["implementationPlanning"]
+    for field in ("planBodyVerification", "optionCandidates", "stepwiseExecution",
+                  "dependencyMigrationRisk", "validationChecklist", "rollbackStrategy",
+                  "requirementCoverage", "variationPointAnalysis"):
+        metadata.pop(field, None)
+    metadata["stages"] = [
+        {key: value for key, value in stage.items() if key != "stepwiseExecution"}
+        for stage in metadata.get("stages", [])
+    ]
+    contracts = find_asset_root(("agents", "common.json"))
+    contract_hashes = {
+        name: _file_snapshot(contracts, name) if contracts else None for name in (
+            "agents/common.json", "agents/roles/analyser.json",
+            "prompts/duties/reverification-worker.json",
+        )
+    }
+    package = Path(__file__).resolve().parent
+    contract_hashes.update({name: _file_snapshot(package, name) for name in (
+        "plan_items.py", "plan_item_evidence.py", "plan_review_context.py", "phases/implementation_planning/authoring.py",
+        "phases/implementation_planning/instructions/plan-body-verification.md",
+    )})
+    files = {name: _file_snapshot(root, name) for name in sorted(paths)}
+    return {
+        "version": 1,
+        "planContext": metadata,
+        "priorReviewHashes": {str(row["id"]): str(row.get("verifiedReviewHash", "")) for row in previous_rows},
+        "items": {str(item["id"]): dict(item) for item in items},
+        "files": files,
+        "dependencies": dependency_scopes(previous_rows),
+        "workers": [row["workerId"] for row in manifest.get("workerAssignments", [])
+                    if row.get("workerId") and not is_critic_worker(row["workerId"])
+                    and not row["workerId"].startswith("report-writer")],
+        "context": _digest([metadata, contract_hashes, manifest.get("workerAssignments"),
+                            manifest.get("agentContract"), manifest.get("invocationAssignments"),
+                            files.get(packet)]),
+        "complete": bool(packet and files.get(packet) and files[packet]["hash"] != "absent"
+                         and all(value and value["hash"] != "absent" for value in contract_hashes.values())),
+    }
+
+
+def dependency_scopes(rows: Sequence[Mapping[str, Any]]) -> dict[str, list[dict[str, Any]]]:
+    return {
+        str(row["id"]): deepcopy(row["verdicts"]) for row in rows
+        if isinstance(row.get("id"), str) and isinstance(row.get("verdicts"), list)
+        and row["verdicts"]
+    }
+
+
+def _vote_dependencies(votes: object, workers: Sequence[str]) -> tuple[set[str], set[str]] | None:
+    if (not isinstance(votes, list) or not votes or not workers
+            or any(not isinstance(vote, Mapping) for vote in votes)
+            or set(workers) - {vote.get("worker") for vote in votes}):
+        return None
+    item_ids, paths = set(), set()
+    for vote in votes:
+        dependencies = vote.get("dependencies")
+        if (vote.get("verdict") not in {"AGREE", "DISAGREE", "SUPPLEMENT"}
+                or vote.get("claimKind") == "fact"
+                or not isinstance(dependencies, Mapping)
+                or dependencies.get("complete") is not True):
+            return None
+        for field in ("itemIds", "paths"):
+            values = dependencies.get(field)
+            if not isinstance(values, list) or any(not isinstance(v, str) or not v for v in values):
+                return None
+        item_ids.update(dependencies["itemIds"])
+        paths.update(dependencies["paths"])
+    return item_ids, paths
+
+
+def _dependency_closure(row: Mapping[str, Any], inputs: Mapping[str, Any]) -> tuple[set[str], set[str]] | None:
+    items = inputs.get("items", {})
+    graph = {**inputs.get("dependencies", {}), str(row["id"]): row.get("verdicts")}
+    pending, item_ids, paths = [str(row["id"])], set(), set()
+    while pending:
+        key = pending.pop()
+        if key in item_ids:
+            continue
+        if key not in items:
+            return None
+        declared = _vote_dependencies(graph.get(key), inputs.get("workers", []))
+        if declared is None:
+            return None
+        if any(not inputs.get("files", {}).get(name)
+               or inputs["files"][name]["hash"] == "absent" for name in declared[1]):
+            return None
+        item_ids.add(key)
+        pending.extend(declared[0])
+        paths.update(declared[1])
+        payload = items[key].get("payload") or {}
+        if key.startswith(("P-Opt-", "P-Var-", "P-Dir-", "P-Dep-", "P-Prep-")):
+            pending.extend(items)
+            paths.update(inputs.get("files", {}))
+        elif key.startswith("P-Step-"):
+            pending.extend(
+                other_id for other_id, other in items.items()
+                if other_id.startswith("P-Step-") and other["payload"].get("stage") == payload.get("stage")
+                and other["payload"].get("step", 0) < payload.get("step", 0)
+            )
+        for field in ("files", "plannedPaths"):
+            paths.update(_payload_paths(payload.get(field)))
+    return item_ids, paths
+
+
+def review_fingerprint(row: Mapping[str, Any], inputs: Mapping[str, Any]) -> str | None:
+    items, files = inputs.get("items", {}), inputs.get("files", {})
+    item = items.get(row.get("id"))
+    if not inputs.get("complete") or not item or row.get("contentHash") != content_hash(item):
+        return None
+    closure = _dependency_closure(row, inputs)
+    if closure is None:
+        return None
+    item_ids, paths = closure
+    if any(name not in files or files[name] is None for name in paths):
+        return None
+    return _digest({
+        "context": inputs["context"],
+        "items": {key: content_hash(items[key]) for key in sorted(item_ids)},
+        "files": {name: files[name] for name in sorted(paths)},
+        "votes": row["verdicts"],
+    })
+
+
+def review_files_unchanged(inputs: Mapping[str, Any], root: Path) -> bool:
+    return all(
+        value == _file_snapshot(root, name)
+        for name, value in inputs.get("files", {}).items()
+    )
+
+
+def reusable_item_ids(
+    rows: Sequence[Mapping[str, Any]], inputs: Mapping[str, Any],
+) -> set[str]:
+    return {
+        str(row["id"]) for row in rows
+        if row.get("verifiedReviewHash")
+        and row["verifiedReviewHash"] == review_fingerprint(row, inputs)
+    }

package/runtime/python/okstra_ctl/plan_items.py

@@ -410,11 +410,6 @@ def _is_plan_wide(item_id: str) -> bool:
 
 
 def content_hash(item: Mapping[str, Any]) -> str:
-    """이 항목 본문의 지문. 문구가 같으면 라운드가 달라도 같은 판정이다.
-
-    라운드 번호만 보면 고치지 않은 항목까지 재검증해야 한다. subject·payload·
-    block·stageScope 가 같으면 그 항목이 가리키는 텍스트는 재작성 전과 같다.
-    """
     payload = {
         "block": item.get("block"),
         "payload": item.get("payload"),
@@ -828,6 +823,14 @@ PLAN_VERIFY_RESPONSE_FORMAT = (
     "**Note**: <the falsification candidate considered and why it is "
     "excluded; required even for AGREE>\n"
     "**Explanation**: <2-3 sentences>\n"
+    '**Dependencies**: {"complete": false, "itemIds": [], "paths": []}\n'
+    "Keep the detailed Note and Explanation above. Set complete=true only when "
+    "you can enumerate ALL direct and transitive evidence dependencies: other "
+    "P-* items in itemIds and whole local files in paths (project-relative). "
+    "Include source files behind citations, not just the citing document. "
+    "If the dependency boundary, dynamic state, an external source, or any "
+    "reference cannot be resolved, keep complete=false. Missing or uncertain "
+    "dependencies cause re-verification; they never suppress your verdict.\n"
 )
 
 
@@ -851,7 +854,7 @@ def with_response_format(queue_markdown: str) -> str:
     return queue_markdown.rstrip("\n") + "\n" + PLAN_VERIFY_RESPONSE_FORMAT
 
 
-def item_cites_build_command(item: Mapping[str, Any]) -> bool:
+def _item_cites_build_command(item: Mapping[str, Any]) -> bool:
     """이 항목이 계획 워크트리에서 실행 불가한 빌드/테스트 명령을 인용하는가."""
     payload = item.get("payload") if isinstance(item.get("payload"), Mapping) else item
     if not isinstance(payload, Mapping):
@@ -914,13 +917,13 @@ def _worker_is_blanket(
     if not votes or any(not _error_verdict(token) for _item_id, token in votes):
         return False
     return any(
-        not item_cites_build_command(_with_payload(items_by_id[item_id], payloads))
+        not _item_cites_build_command(_with_payload(items_by_id[item_id], payloads))
         for item_id, _token in votes
         if item_id in items_by_id
     )
 
 
-def blanket_unverifiable_workers(
+def _blanket_unverifiable_workers(
     items: Sequence[Mapping[str, Any]],
     payloads: Mapping[str, Mapping[str, Any]] | None = None,
 ) -> list[str]:
@@ -1028,7 +1031,7 @@ def next_dispatch(
         str(item["id"]) for item in items
         if isinstance(item.get("id"), str) and item["id"]
     )
-    blanket = tuple(blanket_unverifiable_workers(items, payloads))
+    blanket = tuple(_blanket_unverifiable_workers(items, payloads))
     if blanket:
         return NextDispatch(
             kind="worker-correction",

package/runtime/python/okstra_ctl/plan_review_context.py

@@ -0,0 +1,82 @@
+"""Lossless plan context with conservative dependency-based selection."""
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from .analysis_packet import _heading_lines
+from .plan_item_evidence import _dependency_closure, review_fingerprint
+from .plan_items import content_hash
+
+
+def _packet_excerpt(text: str) -> str:
+    lines = text.splitlines(keepends=True)
+    headings = _heading_lines([line.rstrip("\r\n") for line in lines])
+    omitted: set[int] = set()
+    for index, (start, heading) in enumerate(headings):
+        stop = headings[index + 1][0] - 1 if index + 1 < len(headings) else len(lines)
+        section = "".join(lines[start - 1:stop])
+        generated_census = (
+            heading == "## Coverage Census"
+            and "The fixed worklist for this run. okstra built it from the phase " in section
+            and "| Cell | Scope | Subject | Question |" in section
+        )
+        if heading != "## Section Index" and not generated_census:
+            continue
+        omitted.update(range(start - 1, stop))
+    excerpt = "".join(line for index, line in enumerate(lines) if index not in omitted)
+    if re.search(r"(?im)^###\s+(?:[FC]-|P-)", excerpt):
+        return "".join("> " + line for line in excerpt.splitlines(keepends=True))
+    return excerpt
+
+
+def _supporting_ids(queue: Sequence[str], inputs: Mapping[str, Any]) -> set[str]:
+    items = inputs["items"]
+    selected: set[str] = set()
+    for key in queue:
+        row = {"id": key, "verdicts": inputs.get("dependencies", {}).get(key),
+               "contentHash": content_hash(items[key])}
+        previous = inputs.get("priorReviewHashes", {}).get(key)
+        if not previous or previous != review_fingerprint(row, inputs):
+            return set(items)
+        closure = _dependency_closure(row, inputs)
+        if closure is None:
+            return set(items)
+        selected.update(closure[0])
+    return selected
+
+
+def render_review_context(
+    queue: Sequence[str], inputs: Mapping[str, Any], manifest: Mapping[str, Any], root: Path,
+) -> str:
+    if not inputs.get("complete") or "planContext" not in inputs:
+        return ""
+    packet = str(manifest["analysisPacketPath"])
+    supporting = _supporting_ids(queue, inputs) - set(queue)
+    context = {
+        "planMetadata": inputs["planContext"],
+        "availableEvidencePaths": sorted(name for name in inputs["files"] if name != packet),
+        "supportingItems": [
+            item
+            for key, item in inputs["items"].items() if key in supporting
+        ],
+    }
+    return (
+        "\n## Review context\n\n"
+        "Use the inline packet and plan context below first. The plan items assigned below "
+        "carry their complete payloads; supporting items are context, not extra verdicts. "
+        "Do not reread the full narrative or packet unless a reference is unresolved, "
+        "context is missing, or a cross-item contradiction needs investigation. Read the "
+        "original paths in Inputs in that case and declare all additional dependencies. "
+        "Never infer that an omitted item or an unread source is absent. "
+        "Only the packet's navigation index and generated analysis Coverage Census are "
+        "omitted; task requirements, directives, carry-in, and unknown sections are retained.\n\n"
+        f"### Primary packet excerpt: `{packet}`\n\n"
+        + _packet_excerpt((root / packet).read_text(encoding="utf-8"))
+        + "\n### Plan context (lossless JSON)\n\n"
+        + json.dumps(context, ensure_ascii=False, separators=(",", ":"))
+        + "\n"
+    )

package/runtime/python/okstra_ctl/verdict_blocks.py

@@ -17,6 +17,7 @@ refusing them costs a dispatch cycle and yields no information. A bare
 from __future__ import annotations
 
 import re
+import json
 from dataclasses import dataclass
 
 VERDICT_TOKENS = frozenset({
@@ -64,7 +65,7 @@ _ITEM_RE = re.compile(r"^###[ \t]+(?P<id>[^\s:]+)[ \t]*:?.*$", re.MULTILINE)
 # `_field_match` enforces that an opening `**` is closed exactly once and that
 # a label without bold carries a bullet.
 _FIELD_KEYS = ("Verdict", "Fixability", "Note", "Explanation", "Prior dissent",
-               "Basis", "Your evidence")
+               "Basis", "Your evidence", "Dependencies")
 _CANONICAL_KEYS = {key.lower(): key for key in _FIELD_KEYS}
 _FIELD_RE = re.compile(
     r"^(?P<bullet>[-*+][ \t]+)?(?P<open>\*\*)?"
@@ -234,6 +235,7 @@ class VerdictBlock:
     note: str
     explanation: str
     prior_dissent: str
+    dependencies: dict | None = None
 
 
 def parse_verdict_blocks(text: str) -> dict[str, VerdictBlock]:
@@ -269,6 +271,19 @@ def _block(item_id: str, fields: dict[str, str]) -> VerdictBlock:
                 f"`{fixability or '(missing)'}` — expected one of "
                 f"{sorted(FIXABILITY_VALUES)}"
             )
+    dependencies = None
+    if fields.get("Dependencies"):
+        try:
+            candidate = json.loads(fields["Dependencies"])
+            if (isinstance(candidate, dict) and isinstance(candidate.get("complete"), bool)
+                    and all(isinstance(candidate.get(key), list)
+                            and all(isinstance(value, str) and value for value in candidate[key])
+                            for key in ("itemIds", "paths"))):
+                dependencies = {key: candidate[key] for key in ("complete", "itemIds", "paths")}
+            else:
+                dependencies = {"complete": False, "itemIds": [], "paths": []}
+        except (ValueError, TypeError):
+            dependencies = {"complete": False, "itemIds": [], "paths": []}
     return VerdictBlock(
         item_id=item_id,
         verdict=token,
@@ -277,4 +292,5 @@ def _block(item_id: str, fields: dict[str, str]) -> VerdictBlock:
         note=fields.get("Note", ""),
         explanation=fields.get("Explanation", ""),
         prior_dissent=fields.get("Prior dissent", ""),
+        dependencies=dependencies,
     )

package/runtime/python/okstra_ctl/wizard/engine.py

@@ -123,20 +123,41 @@ def _apply_answer(state: WizardState, prompt: Prompt, value: str) -> str:
     return echo or ""
 
 
+def _automatic_answers(state: WizardState, prompt: Prompt) -> list[tuple[Prompt, str]]:
+    """Answers the wizard takes without showing the screen.
+
+    A one-line pick takes its line. A pick whose builder set `auto_value` takes it
+    unless the user came back to that step through Edit; a group takes each such
+    member and shows the rest.
+    """
+    if _is_lone_choice_pick(prompt):
+        return [(prompt, prompt.options[0].value)]
+    members = prompt.questions if prompt.kind == "pick_group" else [prompt]
+    return [
+        (member, member.auto_value)
+        for member in members
+        if member.kind == "pick"
+        and member.auto_value
+        and member.step not in state.manual_steps
+    ]
+
+
 def next_prompt(state: WizardState) -> Prompt:
-    # 한 줄짜리 picker 를 건너뛰면 그 자리에 다음 화면이 온다. 그것도 한 줄짜리일
-    # 수 있어 반복하되, 같은 step 이 다시 오면(반복 가능한 step) 묻는다.
+    # 자동으로 답한 화면 자리에 다음 화면이 온다. 그것도 자동일 수 있어 반복하되,
+    # 같은 step 이 다시 오면(반복 가능한 step) 묻는다.
     taken: set[str] = set()
     while True:
         prompt = _next_prompt_screen(state)
-        if prompt.step in taken or not _is_lone_choice_pick(prompt):
+        answers = [] if prompt.step in taken else _automatic_answers(state, prompt)
+        if not answers:
             return _native_picker_screen(state, prompt)
         taken.add(prompt.step)
         attempt = copy.deepcopy(state)
         try:
-            _apply_answer(attempt, prompt, prompt.options[0].value)
+            for member, value in answers:
+                _apply_answer(attempt, member, value)
         except WizardError:
-            # 그 한 줄이 거절되면 사용자에게 보여 거절 사유를 받게 한다.
+            # 자동 답이 거절되면 사용자에게 보여 거절 사유를 받게 한다.
             return _native_picker_screen(state, prompt)
         state.__dict__.update(attempt.__dict__)
 

package/runtime/python/okstra_ctl/wizard/registry.py

@@ -243,6 +243,8 @@ def _submit_edit_target(state: WizardState, value: str) -> Optional[str]:
         _reset_from(state, value)
     else:
         raise WizardError(f"unknown step: {value!r}")
+    if value not in state.manual_steps:
+        state.manual_steps.append(value)
     state.edit_target = value
     state.confirmed = None
     state.edit_target = ""

package/runtime/python/okstra_ctl/wizard/state.py

@@ -143,6 +143,8 @@ class WizardState:
 
     # bookkeeping
     answered: list[str] = field(default_factory=list)
+    # Steps the user came back to through Edit; their auto_value no longer applies.
+    manual_steps: list[str] = field(default_factory=list)
 
     def to_json(self) -> dict[str, Any]:
         payload = asdict(self)
@@ -181,6 +183,9 @@ class Prompt:
     multi: bool = False  # only meaningful when kind == "pick"
     # only meaningful when kind == "pick_group": one entry per AskUserQuestion tab
     questions: list["Prompt"] = field(default_factory=list)
+    # The answer the wizard takes without asking, because it comes from a recorded
+    # source; the confirm screen shows it and its Edit menu asks for it again.
+    auto_value: str = ""
 
     def __post_init__(self) -> None:
         """자유 입력 선택지는 언제나 마지막이다.