okstra 0.223.0 → 0.224.0

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/report_finalize.py

@@ -1154,7 +1154,9 @@ def _context_from_args(args: argparse.Namespace) -> FinalizeContext:
         team_state_path = resolve_project_path(
             project_root, require_string(manifest, "teamStatePath")
         )
-    report_path = resolve_project_path(project_root, args.report)
+    report_path = resolve_project_path(
+        project_root, args.report or require_string(manifest, "expectedReportRecordPath")
+    )
     return FinalizeContext.from_manifest(
         project_root=project_root,
         workspace_root=Path(args.workspace_root).resolve(),
@@ -1213,8 +1215,11 @@ def _parser() -> argparse.ArgumentParser:
     parser.add_argument("--run-manifest", required=True)
     parser.add_argument(
         "--report",
-        required=True,
-        help="final-report record (.data.json); a leftover markdown path still locates the sibling record",
+        default="",
+        help=(
+            "final-report record (.data.json); defaults to the run manifest's "
+            "expectedReportRecordPath. A leftover markdown path still locates the sibling record"
+        ),
     )
     # `okstra report-finalize` 래퍼(src/lib/python-command.mts)가 넣고, 사용자가
     # 직접 주면 거절한다. usage 에 필수로 찍히면 그 거절과 모순되므로 감춘다.

package/runtime/python/okstra_ctl/run.py

@@ -4274,6 +4274,9 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         )
         carry = derive_stage_fix_carry(
             Path(ctx["RUN_DIR"]), ctx.get("EXECUTOR_WORKTREE_PATH", ""),
+            plan_run_root=Path(inp.approved_plan_path).resolve().parents[1],
+            stage=stage_run_claim.stage,
+            project_root=Path(ctx["PROJECT_ROOT"]),
         )
         ctx["FIX_RUN_CONTEXT"] = carry.as_prompt_markdown() if carry else ""
 

package/runtime/python/okstra_ctl/stage_fix_carry.py

@@ -1,8 +1,9 @@
-"""Derive the fix-run carry for an implementation stage whose previous run
-ended with one or more verifier FAIL verdicts.
+"""Derive the fix-run carry for an implementation stage that is re-entered to
+fix a defect: either a verifier FAIL in the stage's previous run, or acceptance
+blockers a final-verification found after the stage was settled and reopened.
 
-Pure read-side: scans the stage run directory's assembled final-report data.json
-files and the stage worktree HEAD.
+Pure read-side: scans consumers.jsonl, the reopen evidence report, the stage run
+directory's assembled final-report data.json files and the stage worktree HEAD.
 Returns None when the upcoming run is not a fix run, so callers can treat
 "no carry" and "first run on this stage" identically.
 """
@@ -14,10 +15,15 @@ import subprocess
 from dataclasses import dataclass
 from pathlib import Path
 
+from .consumers import read_consumers
 from .json_boundary import JsonBoundaryError, load_owned_object
 from .phases.implementation.validation import lead_fixed_verifiers
 
 _REPORT_RE = re.compile(r"final-report-implementation-(\d+)\.data\.json$")
+_SEQ_RE = re.compile(r"-(\d+)\.data\.json$")
+
+SOURCE_VERIFIER = "verifier"
+SOURCE_FINAL_VERIFICATION = "final-verification"
 
 
 @dataclass(frozen=True)
@@ -28,16 +34,30 @@ class StageFixCarry:
     failed_verifiers: list[str]
     blocking_findings: list[str]
     routing_recommendation: str
+    source: str = SOURCE_VERIFIER
+    reopen_reason: str = ""
+    verification_scope: str = ""
 
     def as_prompt_markdown(self) -> str:
-        lines = [
-            "## Fix-Run Carry (this run fixes a prior FAIL)",
-            "",
-            f"- Previous report (data.json SSOT): `{self.prev_report_path}`",
-            f"- Previous run HEAD (fix-diff base): `{self.prev_head_commit}`",
-            f"- Failed verifiers: {', '.join(self.failed_verifiers)}",
-            "- Carried blocking findings:",
-        ]
+        if self.source == SOURCE_FINAL_VERIFICATION:
+            lines = [
+                "## Fix-Run Carry (this run fixes final-verification acceptance blockers)",
+                "",
+                f"- Final-verification report (data.json SSOT): `{self.prev_report_path}`",
+                f"- Reopened stage head (fix-diff base): `{self.prev_head_commit}`",
+                f"- Reopen reason: {self.reopen_reason}",
+                f"- Verification scope: {self.verification_scope or 'unrecorded'}",
+                "- Carried acceptance blockers:",
+            ]
+        else:
+            lines = [
+                "## Fix-Run Carry (this run fixes a prior FAIL)",
+                "",
+                f"- Previous report (data.json SSOT): `{self.prev_report_path}`",
+                f"- Previous run HEAD (fix-diff base): `{self.prev_head_commit}`",
+                f"- Failed verifiers: {', '.join(self.failed_verifiers)}",
+                "- Carried blocking findings:",
+            ]
         lines.extend(f"  - {finding}" for finding in self.blocking_findings)
         if self.routing_recommendation:
             lines.append(
@@ -49,16 +69,39 @@ class StageFixCarry:
             "(`_implementation-verifier.md` § Fix-run incremental scope, "
             "`report-writer.md` § Fix-run incremental authoring).",
             "This block is inlined into the executor and verifier prompts by "
-            "`initial_prompt_materialization`; do not transcribe it by hand. "
-            "Lead duties: pass the previous data.json path above as read context "
-            "to the report-writer dispatch so it updates only changed narrative blocks.",
+            "`initial_prompt_materialization`; do not transcribe it by hand.",
         ])
+        if self.source == SOURCE_FINAL_VERIFICATION:
+            # 블로커 행에는 stage 필드가 없다(AcceptanceBlockerRow) — whole-task 검증이면 소유 판단을 실행자에게 넘긴다.
+            if self.verification_scope != "single-stage":
+                lines.append(
+                    "Blocker rows name no stage: fix the blockers this stage owns, "
+                    "as the reopen reason states, and cite the others as out of scope."
+                )
+        else:
+            lines.append(
+                "Lead duties: pass the previous data.json path above as read context "
+                "to the report-writer dispatch so it updates only changed narrative blocks."
+            )
         return "\n".join(lines)
 
 
 def derive_stage_fix_carry(
-    stage_run_dir: Path, worktree_path: str,
+    stage_run_dir: Path, worktree_path: str, *,
+    plan_run_root: Path | None = None,
+    stage: int | None = None,
+    project_root: Path | None = None,
 ) -> StageFixCarry | None:
+    """A stage reopened over a final-verification report carries that report's
+    blockers; otherwise the latest implementation report's verifier FAILs.
+
+    The two never merge: a reopen withdraws a `done` row, and that `done` already
+    settled every verdict of the implementation report before it.
+    """
+    if plan_run_root is not None and stage is not None and project_root is not None:
+        carry = _reopen_carry(plan_run_root, stage, project_root, worktree_path)
+        if carry is not None:
+            return carry
     report = _latest_report(Path(stage_run_dir))
     if report is None:
         return None
@@ -91,6 +134,65 @@ def derive_stage_fix_carry(
     )
 
 
+def _reopen_carry(
+    plan_run_root: Path, stage: int, project_root: Path, worktree_path: str,
+) -> StageFixCarry | None:
+    # 이 run 의 claim 이 이미 `started` 행을 붙였으므로 마지막 종결 행(done/failed)을 본다.
+    settled = [
+        row for row in read_consumers(Path(plan_run_root))
+        if row.get("stage") == stage and row.get("status") in ("done", "failed")
+    ]
+    if not settled:
+        return None
+    row = settled[-1]
+    evidence = str(row.get("evidence_path") or "")
+    if row.get("reopened_by") != "stage-reopen" or not evidence:
+        return None
+    report = Path(evidence)
+    if not report.is_absolute():
+        report = Path(project_root) / report
+    try:
+        data = load_owned_object(report, artifact="final-verification final report")
+    except (OSError, JsonBoundaryError):
+        return None
+    if (data.get("header") or {}).get("taskType") != "final-verification":
+        return None
+    fv = data.get("finalVerification")
+    if not isinstance(fv, dict):
+        return None
+    blockers = [
+        _blocker_line(item) for item in fv.get("acceptanceBlockers") or []
+        if isinstance(item, dict)
+    ]
+    if not blockers:
+        return None
+    # fix-diff 기준은 final-verification 이 판정한 head — reopen 이 철회한 done 행의 head 다.
+    head = str(row.get("head_commit") or "") or _git_head(worktree_path)
+    if not head:
+        return None
+    seq = _SEQ_RE.search(report.name)
+    return StageFixCarry(
+        prev_report_path=str(report),
+        prev_report_seq=seq.group(1) if seq else "",
+        prev_head_commit=head,
+        failed_verifiers=[],
+        blocking_findings=blockers,
+        routing_recommendation=_routing_line(fv.get("routingRecommendation")),
+        source=SOURCE_FINAL_VERIFICATION,
+        reopen_reason=str(row.get("reason") or ""),
+        verification_scope=str(data.get("verificationScope") or ""),
+    )
+
+
+def _blocker_line(row: dict) -> str:
+    return (
+        f"{row.get('id') or '<no id>'} ({row.get('severity') or 'unrated'}, "
+        f"follow-up phase: {row.get('followUpPhase') or 'unrecorded'}): "
+        f"{str(row.get('statement') or '').strip()} — evidence: "
+        f"{str(row.get('evidence') or '').strip()}"
+    )
+
+
 def _blocking_findings(data: dict, failed: list[dict]) -> list[str]:
     """이전 run 을 FAIL 로 만든 finding 목록.
 

package/runtime/python/okstra_ctl/stage_rebase.py

@@ -118,6 +118,9 @@ def synchronize_stage_stack(
         stage = by_number[number]
         if not row or number not in done or stage.get("cancelled"):
             continue
+        # A reopened predecessor has no done row; its dependent waits for the next one.
+        if any(dep not in done for dep in stage.get("depends_on") or []):
+            continue
         active = statuses.get(number) == "started" or row.get("status") == "active"
         if _synchronize_recorded_stage(
             project_root,

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:
         """자유 입력 선택지는 언제나 마지막이다.