okstra 0.198.2 → 0.199.1

package/runtime/python/okstra_ctl/plan_items.py

@@ -930,11 +930,36 @@ class NextDispatch:
         }
 
 
+def self_fix_rounds(verification: Mapping[str, Any]) -> frozenset[int]:
+    """마지막 검증 라운드 번호와 자동 수정 횟수를 구분한다."""
+    rounds = frozenset(
+        group["round"] for group in (verification.get("selfFixGroups") or [])
+        if isinstance(group, Mapping)
+        and type(group.get("round")) is int and group["round"] > 0
+    )
+    applied = verification.get("selfFixRoundsApplied")
+    if not rounds and type(applied) is int and applied > 0:
+        return frozenset({applied})
+    return rounds
+
+
+def lead_decision_basis(item: Mapping[str, Any]) -> str:
+    """본문·범위·판정이 바뀌면 이전 리드 결정으로 새 쟁점을 해소할 수 없다."""
+    basis = {key: item.get(key) for key in (
+        "id", "subject", "block", "stageScope", "contentHash",
+        "verifiedContentHash", "verdicts",
+    )}
+    return hashlib.sha256(
+        json.dumps(basis, sort_keys=True, ensure_ascii=False).encode("utf-8")
+    ).hexdigest()
+
+
 def next_dispatch(
     items: Sequence[Mapping[str, Any]],
     payloads: Mapping[str, Mapping[str, Any]] | None = None,
     *,
     critic_rostered: bool = True,
+    decision_items: Sequence[Mapping[str, Any]] = (),
 ) -> NextDispatch:
     """환경 전용 UNVERIFIABLE 은 전체 라운드를 만들지 않는다. 일괄 오류만 그 워커.
 
@@ -945,6 +970,19 @@ def next_dispatch(
     `critic-tie` 다: critic 이 있는 run 을 사용자 결정으로 보내는 쪽이 더
     나쁜 오답이다.
     """
+    for authority in ("lead", "user"):
+        pending = tuple(
+            str(row["id"]) for row in decision_items
+            if row.get("decisionAuthority") == authority
+            and not row.get("leadDecisionApplied")
+        )
+        if pending:
+            return NextDispatch(
+                kind=f"{authority}-decision", workers=(), item_ids=pending,
+                reason="automatic self-fix finished; resolve remaining decisions without another worker batch",
+            )
+    if decision_items:
+        return NextDispatch(kind="none", workers=(), item_ids=(), reason="remaining decisions resolved")
     assigned = tuple(
         str(item["id"]) for item in items
         if isinstance(item.get("id"), str) and item["id"]
@@ -981,10 +1019,7 @@ def next_dispatch(
                 "approval decision per item"
             ),
         )
-    return NextDispatch(
-        kind="none", workers=(), item_ids=(),
-        reason="no worker batch",
-    )
+    return NextDispatch(kind="none", workers=(), item_ids=(), reason="no worker batch")
 
 
 def correction_prompt_text(queue_markdown: str) -> str:
@@ -1000,4 +1035,3 @@ def critic_tie_prompt_text(queue_markdown: str) -> str:
 def reverify_prompt_text(queue_markdown: str) -> str:
     """라운드 2+ 프롬프트. 직전 반대 의견을 읽으라는 지시가 큐보다 앞이다."""
     return f"{REVERIFY_PREAMBLE.rstrip()}\n\n{queue_markdown.lstrip()}"
-

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -37,10 +37,12 @@ from .plan_items import (
     critic_tie_prompt_text,
     dispatch_item_ids,
     extract_plan_items,
+    lead_decision_basis,
     next_dispatch,
     planning_stage_ledger,
     reverify_item_ids,
     reverify_prompt_text,
+    self_fix_rounds,
     tie_vote_item_ids,
     voting_analyser_keys,
     with_rendered_by,
@@ -301,6 +303,12 @@ def _parser() -> argparse.ArgumentParser:
 
 
 def _add_dispatch_commands(commands: Any) -> None:
+    resolve = commands.add_parser(
+        "resolve-dissent", help="record an evidence-based lead decision after the single self-fix",
+    )
+    resolve.add_argument("--state", type=Path, required=True)
+    resolve.add_argument("--item", required=True)
+    resolve.add_argument("--decision-file", type=Path, required=True)
     nxt = commands.add_parser(
         "next-dispatch",
         help="decide whether this round opens a worker batch",
@@ -1631,6 +1639,12 @@ def _plan_gate_summary(verification: Mapping[str, Any]) -> dict[str, Any]:
 
 
 def _record_self_fixes(args: argparse.Namespace, audit: list[object], verification: dict[str, Any]) -> None:
+    previous = self_fix_rounds(verification)
+    if (args.self_fix_group or args.self_fix_note) and previous - {args.round_number}:
+        raise PlanItemContractError(
+            "automatic self-fix is limited to one rewrite; resolve remaining "
+            "items through a lead decision or user confirmation"
+        )
     notes: dict[str, str] = {}
     known = {item.get("id") for item in audit if isinstance(item, Mapping)}
     if args.self_fix_group and not args.self_fix_stop_reason:
@@ -1653,6 +1667,8 @@ def _record_self_fixes(args: argparse.Namespace, audit: list[object], verificati
     for item in audit:
         if isinstance(item, dict) and item.get("id") in notes:
             item["selfFixNote"] = notes[item["id"]]
+    if notes and not args.self_fix_group and not previous:
+        raise PlanItemContractError("--self-fix-note requires --self-fix-group to account for the rewrite")
     groups = []
     for raw in args.self_fix_group:
         filename, separator, item_ids = raw.partition("=")
@@ -1780,6 +1796,7 @@ def _complete_round(args: argparse.Namespace) -> dict[str, Any]:
             raise PlanItemContractError(
                 "advisory plan-body gating forbids the self-fix loop"
             )
+    _record_self_fixes(args, audit, verification)
     _reject_round_gap(history, args.round_number)
     snapshots, summary = _round_snapshots(current, verification, args.round_number)
     _record_audit_round(audit, snapshots, args.round_number)
@@ -1808,21 +1825,17 @@ def _complete_round(args: argparse.Namespace) -> dict[str, Any]:
                          "setAside": summary["setAside"],
                          "participatingAnalysers": {"rostered": rostered, "voting": voting},
                          "uniformVerifiers": uniform})
-    _record_self_fixes(args, audit, verification)
     if args.self_fix_group:
         data["selfFixRoundsApplied"] = args.round_number
     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)
-    payloads = _prepared_payloads(args.run_manifest)
     return {
         "ok": True,
         "operation": "complete-round",
         "path": str(args.state),
         "gateResult": gate,
-        "nextDispatch": next_dispatch(
-            current, payloads, critic_rostered=critic_is_rostered(manifest),
-        ).as_dict(),
+        "nextDispatch": _state_next_dispatch(args).as_dict(),
     }
 
 
@@ -1859,14 +1872,55 @@ def _rostered_critic(run_manifest: Path | None) -> bool:
 
 
 def _state_next_dispatch(args: argparse.Namespace) -> NextDispatch:
-    _data, current, _audit, _history = _round_inputs(args)
+    data, current, _audit, _history = _round_inputs(args)
     run_manifest = getattr(args, "run_manifest", None)
     payloads = _prepared_payloads(run_manifest)
     return next_dispatch(
         current, payloads, critic_rostered=_rostered_critic(run_manifest),
+        decision_items=(
+            _plan_gate_summary(data["planBodyVerification"])["items"]
+            if self_fix_rounds(data["planBodyVerification"]) else ()
+        ),
     )
 
 
+def _resolve_dissent(args: argparse.Namespace) -> dict[str, Any]:
+    data, current, _audit, history = _round_inputs(args)
+    verification = data["planBodyVerification"]
+    item = next((row for row in current if row.get("id") == args.item), None)
+    if item is None:
+        raise PlanItemContractError(f"unknown plan item `{args.item}`")
+    closed = {row.get("round") for row in history if isinstance(row, Mapping)}
+    if any(row.get("round") not in closed for row in item.get("verdicts", [])):
+        raise PlanItemContractError("complete-round must record every verdict before a lead decision")
+    summary = _plan_gate_summary(verification)
+    authority = next(row for row in summary["items"] if row["id"] == args.item)
+    if authority["decisionAuthority"] != "lead":
+        raise PlanItemContractError(
+            f"`{args.item}` is not a lead-owned judgement after self-fix; "
+            "use user confirmation for unresolved facts, requirements, risks or preferences"
+        )
+    try:
+        decision = args.decision_file.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeError) as exc:
+        raise PlanItemContractError(f"cannot read lead decision: {exc}") from exc
+    if not decision:
+        raise PlanItemContractError("lead decision must state the decision, authority and cited evidence")
+    item["leadDecision"] = {"basisHash": lead_decision_basis(item), "decision": decision}
+    entry = {"planItem": args.item, "workerRole": "lead", "body": decision}
+    dissent = verification.setdefault("dissentLog", [])
+    if entry not in dissent:
+        dissent.append(entry)
+    summary = _plan_gate_summary(verification)
+    verification.update({
+        "gateResult": summary["recomputed"], "gateBlockedBy": summary["blockedBy"],
+        "setAside": summary["setAside"],
+    })
+    write_json_atomic(args.state, data)
+    return {"ok": True, "operation": "resolve-dissent", "itemId": args.item,
+            "gateResult": summary["recomputed"]}
+
+
 def _next_dispatch(args: argparse.Namespace) -> dict[str, Any]:
     decision = _state_next_dispatch(args)
     return {"ok": True, "operation": "next-dispatch", **decision.as_dict()}
@@ -1946,6 +2000,7 @@ _HANDLERS = {
     "apply-verdicts": _apply_verdicts,
     "complete-round": _complete_round,
     "next-dispatch": _next_dispatch,
+    "resolve-dissent": _resolve_dissent,
     "correction-prompt": _correction_prompt,
 }
 

package/runtime/python/okstra_ctl/recap.py

@@ -26,6 +26,7 @@ from okstra_project import (
     find_task_root,
     list_project_tasks,
     read_task_key,
+    read_task_manifest,
     resolve_project_root,
     tasks_root,
 )
@@ -109,6 +110,7 @@ def rerun_readiness(project_root: Path, runs: list[dict]) -> dict | None:
 
 
 def assemble_recap(task_root: Path, project_root: Path) -> dict:
+    manifest = read_task_manifest(task_root) or {}
     # timeline 항목의 status / workflowSnapshot / reportRecordPath 는 준비 시점
     # 값이다. 각 run 의 종료 상태는 그 run 의 run-manifest 에서 덮어쓴다.
     runs = [
@@ -142,6 +144,8 @@ def assemble_recap(task_root: Path, project_root: Path) -> dict:
     return {
         "taskKey": read_task_key(task_root),
         "runCount": len(runs),
+        "workStatus": manifest.get("workStatus", ""),
+        "latestWorkRecordPath": manifest.get("latestWorkRecordPath", ""),
         "transitions": transitions,
         "latestPhaseStates": latest_states,
         # `null` when nothing is waiting to be carried — the key is always
@@ -177,6 +181,7 @@ def _group_catalog(project_root: Path, task_group: str) -> dict[str, dict]:
 def _memory_block(entry: group_context.MemoryEntry) -> dict[str, Any]:
     return {
         "date": entry.date,
+        "source": entry.source,
         "taskType": entry.task_type,
         "seq": entry.seq,
         "nextPhase": entry.next_phase,
@@ -237,6 +242,7 @@ def assemble_group_recap(project_root: Path, task_group: str) -> dict:
             "currentPhaseState": str(catalog.get("currentPhaseState") or "") if catalog else "",
             "latestRunStatus": str(catalog.get("latestRunStatus") or "") if catalog else "",
             "workStatus": str(catalog.get("workStatus") or "") if catalog else "",
+            "latestWorkRecordPath": str(catalog.get("latestWorkRecordPath") or "") if catalog else "",
             "nextRecommendedPhase": pointer,
             "runCount": len(_load_timeline(task_root)) if task_root else 0,
             "reportPath": (

package/runtime/python/okstra_ctl/render.py

@@ -921,6 +921,7 @@ def render_task_catalog_discovery(output_path: str, ctx: dict) -> None:
         if not task_key:
             continue
         task_root = manifest_path.parent
+        identity = task_key.split(":")
         timeline_relative = s(manifest, "historyTimelinePath").strip()
         timeline_file = (
             (project_root / timeline_relative)
@@ -947,16 +948,17 @@ def render_task_catalog_discovery(output_path: str, ctx: dict) -> None:
         entries.append(
             {
                 "taskKey": task_key,
-                "taskGroup": s(manifest, "taskGroup"),
-                "taskId": s(manifest, "taskId"),
-                "taskGroupPathSegment": s(manifest, "taskGroupPathSegment"),
-                "taskIdPathSegment": s(manifest, "taskIdPathSegment"),
+                "taskGroup": s(manifest, "taskGroup") or (identity[1] if len(identity) == 3 else ""),
+                "taskId": s(manifest, "taskId") or (identity[2] if len(identity) == 3 else ""),
+                "taskGroupPathSegment": s(manifest, "taskGroupPathSegment") or task_root.parent.name,
+                "taskIdPathSegment": s(manifest, "taskIdPathSegment") or task_root.name,
                 "taskType": s(manifest, "taskType"),
                 "workCategory": s(manifest, "workCategory"),
                 "currentStatus": s(manifest, "currentStatus"),
                 "workStatus": s(manifest, "workStatus"),
                 "workStatusUpdatedAt": s(manifest, "workStatusUpdatedAt"),
                 "workStatusNote": s(manifest, "workStatusNote"),
+                "latestWorkRecordPath": s(manifest, "latestWorkRecordPath"),
                 "updatedAt": s(manifest, "updatedAt"),
                 "currentPhase": (workflow or {}).get("currentPhase", "")
                 if isinstance(workflow, dict)
@@ -1466,6 +1468,8 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
         "workStatus": existing.get("workStatus", ""),
         "workStatusUpdatedAt": existing.get("workStatusUpdatedAt", ""),
         "workStatusNote": existing.get("workStatusNote", ""),
+        "latestWorkRecordPath": existing.get("latestWorkRecordPath", ""),
+        "registrationSource": existing.get("registrationSource", ""),
         "taskBriefPath": ctx.get("BRIEF_RELATIVE_PATH", ""),
         "recommendedWorkers": reviewers,
         "relatedTasks": related_tasks,

package/runtime/python/okstra_ctl/report_narrative.py

@@ -144,7 +144,7 @@ def _without_machine_owned_required(node: Any, *, negated: bool = False) -> Any:
     return result
 
 
-def _writer_owned_schema(schema: Mapping[str, Any]) -> dict[str, Any]:
+def writer_owned_schema(schema: Mapping[str, Any]) -> dict[str, Any]:
     """작성자가 쓴 서사에 걸 값 제약 — 완성 리포트 스키마에서 잘라 온다.
 
     `report-narrative-v3.0.schema.json` 은 최상위 **이름** 허용목록이고 값은
@@ -176,7 +176,7 @@ def _writer_owned_schema(schema: Mapping[str, Any]) -> dict[str, Any]:
 
 def validate_writer_owned(data: Mapping[str, Any], schema: Mapping[str, Any]) -> list[str]:
     """작성자 소유 값 제약으로 서사 자료를 검증한다 — `parse_narrative` 와 같은 스키마."""
-    return validate(dict(data), _writer_owned_schema(schema))
+    return validate(dict(data), writer_owned_schema(schema))
 
 
 def writer_owned_path_defect(path: str) -> str | None:
@@ -570,7 +570,7 @@ def parse_narrative(markdown: str, schema: Mapping[str, Any]) -> dict[str, Any]:
     """Markdown을 작성자 소유 자료로 읽고, 소유권 표면과 값 제약을 검증한다.
 
     `schema` 는 완성 리포트 스키마다. 이름·타입 해석과 값 검증이 모두 그
-    한 벌에서 나온다(`_writer_owned_schema`). 값 단계의 결함(강제 변환·모양·
+    한 벌에서 나온다(`writer_owned_schema`). 값 단계의 결함(강제 변환·모양·
     허용되지 않는 필드)과 스키마 검증의 결함을 한 예외에 모두 싣는다 — 값
     단계가 보고한 자리는 스키마 검증에서 다시 말하지 않는다.
     """
@@ -608,7 +608,7 @@ def parse_narrative_structure(
         )
     errors = [
         error
-        for error in validate(result, _writer_owned_schema(schema))
+        for error in validate(result, writer_owned_schema(schema))
         if not defects.covers(error)
     ]
     return result, defects.messages + errors

package/runtime/python/okstra_ctl/report_synthesis_packet.py

@@ -11,6 +11,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Mapping
 
+from .analysis_packet import reference_source_extracts
 from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
 from .implementation_options import (
     CANDIDATE_COMPARISON_ROUTING,
@@ -22,7 +23,8 @@ from .implementation_options import (
     MIN_FEASIBLE_VOTES,
     NO_VALID_OPTIONS_ROUTING,
 )
-from .report_narrative import writer_owned_data
+from .report_narrative import writer_owned_data, writer_owned_schema
+from .schema_excerpt import build_schema_excerpt
 from .scope_provenance import brief_end_state_id_sequence
 
 from .exact_coverage import COVERAGE_VERDICT_PRECEDENCE
@@ -297,6 +299,7 @@ class ReportSynthesisPacket:
             "- Responsibility: write the complete human-readable narrative while preserving settled values",
             "- Runtime-owned values: session identifiers, token usage, estimated cost, "
             "user response carry-in",
+            "- Accounting details stay in the JSON snapshot; assembly supplies them.",
             "- Validation: source digest match, writer-owned fields, all defects collected",
         ]
         # 작성자가 실제로 읽는 것은 마크다운이다. JSON 정본에만 실으면 지시가
@@ -305,9 +308,8 @@ class ReportSynthesisPacket:
         lines.extend(f"- {text}" for text in self._schema_instructions())
         lines.extend(f"- {text}" for text in self._task_instructions())
         lines.extend(f"- {text}" for text in self._carry_instructions())
-        lines.extend(_accounting_markdown(self.accounting_snapshot))
         for source in self.sources:
-            lines.extend(_source_markdown(source))
+            lines.extend(_source_markdown(source, self.task_type, self.sources))
         return "\n".join(lines).rstrip() + "\n"
 
 
@@ -324,8 +326,50 @@ _SOURCE_FIELDS = (
 )
 
 
-def _source_markdown(source: ReportSynthesisSource) -> list[str]:
+def _source_markdown(
+    source: ReportSynthesisSource, task_type: str,
+    sources: tuple[ReportSynthesisSource, ...],
+) -> list[str]:
     content = source.content.rstrip("\n")
+    view = []
+    if source.label == "Analysis packet":
+        texts = {item.label: item.content for item in sources}
+        content = reference_source_extracts(
+            source.content, task_type,
+            brief_text=texts.get("Task brief", ""),
+            profile_text=texts.get("Analysis profile", ""),
+            reference_text=texts.get("Reference expectations", ""),
+            clarification_text=texts.get("Clarification response", ""),
+        ).rstrip("\n")
+        if content != source.content.rstrip("\n"):
+            view = [
+                "- View: repeated extracts refer to frozen sources below; "
+                "the original line index is omitted. The digest identifies "
+                "the frozen original.",
+            ]
+    if source.label == "Final report schema":
+        try:
+            schema = json.loads(source.content)
+        except json.JSONDecodeError:
+            schema = {}
+            view = ["- View: schema is not JSON; the original text is retained."]
+        if isinstance(schema, dict) and schema.get("properties"):
+            # 원본과 해시는 JSON 보관본에 남긴다. 저작용 읽기에는 검증기와
+            # 같은 소유권 투영을 쓰고, 도달하지 않는 정의만 기존 발췌기로 뺀다.
+            owned = writer_owned_schema(schema)
+            # 부분 서사 검증에서 빠지는 루트 조건도 작성 지침에는 남긴다.
+            # 판정별 금지 필드와 후속 작업 조건은 최종 조립에 적용된다.
+            owned["allOf"] = schema.get("allOf", [])
+            owned["required"] = [
+                key for key in schema.get("required", [])
+                if key in owned["properties"]
+            ]
+            excerpt = build_schema_excerpt(owned, task_type)
+            content = json.dumps(excerpt, ensure_ascii=False, indent=2)
+            view = [
+                "- View: writer-owned schema excerpt; the digest identifies the "
+                "frozen original. Task-specific requirements are listed above.",
+            ]
     longest = max((len(run) for run in re.findall(r"`+", content)), default=0)
     fence = "`" * max(3, longest + 1)
     return [
@@ -335,6 +379,7 @@ def _source_markdown(source: ReportSynthesisSource) -> list[str]:
         f"- Owner: `{source.owner}`",
         f"- Path: `{source.path}`",
         f"- Digest: `{source.digest}`",
+        *view,
         "",
         f"{fence}text",
         content,
@@ -342,42 +387,6 @@ def _source_markdown(source: ReportSynthesisSource) -> list[str]:
     ]
 
 
-def _accounting_markdown(snapshot: Mapping[str, Any]) -> list[str]:
-    summary = snapshot.get("usageSummary")
-    usage_summary = summary if isinstance(summary, Mapping) else {}
-    estimated = usage_summary.get("estimatedCostUsd")
-    estimated_cost = estimated if isinstance(estimated, Mapping) else {}
-    sessions = snapshot.get("leadSessionIds")
-    lead_sessions = sessions if isinstance(sessions, list) else []
-    lines = [
-        "",
-        "## Runtime-owned accounting snapshot",
-        "",
-        "- Lead sessions: " + (", ".join(map(str, lead_sessions)) or "not recorded"),
-        f"- Total tokens: {usage_summary.get('grandTotalTokens', 'not recorded')}",
-        f"- Estimated cost USD: {estimated_cost.get('grandTotal', 'not recorded')}",
-    ]
-    workers = snapshot.get("workerUsage")
-    if not isinstance(workers, list):
-        return lines
-    for worker in workers:
-        if not isinstance(worker, Mapping):
-            continue
-        usage = worker.get("usage")
-        usage_value = usage if isinstance(usage, Mapping) else {}
-        cost = usage_value.get(
-            "estimatedCostUsd",
-            usage_value.get("cliEstimatedCostUsd", "not recorded"),
-        )
-        lines.append(
-            "- Worker "
-            f"{worker.get('workerId', 'unknown')}: "
-            f"tokens={usage_value.get('totalTokens', 'not recorded')}, "
-            f"costUsd={cost}"
-        )
-    return lines
-
-
 def _string(value: object) -> str:
     return value.strip() if isinstance(value, str) else ""
 

package/runtime/python/okstra_ctl/run.py

@@ -76,6 +76,7 @@ from .implementation_direction import (
 from .qa_commands import format_errors as _format_qa_errors, validate_qa_commands
 from .material import (
     build_analysis_material,
+    direct_work_context,
     related_tasks_bullets,
     related_tasks_inline,
     resolve_related_tasks,
@@ -3803,6 +3804,10 @@ def _write_instruction_set_sources(
         stage_ledger_json=render_stage_ledger(stage_ledger),
         stage_ledger_notice=stage_ledger_notice(stage_ledger),
         prior_planning_summary=prior_planning_summary,
+        direct_work_text=direct_work_context(
+            Path(ctx["PROJECT_ROOT"]), ctx["TASK_KEY"],
+            json.loads(ctx.get("RELATED_TASKS_JSON", "[]")),
+        ),
     )
     if inp.task_type in ANALYSIS_TASK_TYPES:
         packet += (