okstra 0.200.0 → 0.201.0

package/runtime/python/okstra_ctl/report_synthesis_packet.py

@@ -2,15 +2,17 @@
 from __future__ import annotations
 
 import copy
-import hashlib
 import json
 import os
 import re
 import tempfile
+from collections import Counter
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Mapping
 
+from okstra_token_usage.blocks import accounting_workers
+
 from .analysis_packet import reference_source_extracts
 from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
 from .implementation_options import (
@@ -54,7 +56,6 @@ class ReportSynthesisSource:
     label: str
     owner: str
     path: str
-    digest: str
     content: str
 
     def to_dict(self) -> dict[str, str]:
@@ -62,7 +63,6 @@ class ReportSynthesisSource:
             "label": self.label,
             "owner": self.owner,
             "path": self.path,
-            "digest": self.digest,
             "content": self.content,
         }
 
@@ -164,6 +164,17 @@ class ReportSynthesisPacket:
         return ["carried-stages-unchanged"] if self.incremental_decision else []
 
     def _task_instructions(self) -> list[str]:
+        if self.task_type == "technical-verification":
+            return [
+                "Copy sourceReport, sourceDataSha256, scope and every fact identity "
+                "from the frozen technical input embedded in the Analysis packet.",
+                "Inspect the run-local plans and command logs cited by settled worker "
+                "results. These cited experiment artifacts are part of this task's "
+                "evidence scope. Record one check per fact and retain limitations.",
+                "Route only to implementation-option-selection with one matching "
+                "phase-continuation. Evidence does not approve adoption or replace "
+                "independent candidate feasibility votes.",
+            ]
         if self.task_type == "implementation-planning":
             return self._planning_requirement_instructions()
         if self.task_type != "implementation-option-selection":
@@ -206,6 +217,16 @@ class ReportSynthesisPacket:
             "supplied one feasibility vote, at least "
             f"{MIN_FEASIBLE_VOTES} votes are `feasible`, and both `safetyBlockers` "
             "and `unresolvedFeasibilityFacts` are empty.",
+            ("Classify each `unresolvedFeasibilityFacts` entry with `resolutionKind`: "
+            "`user-decision` requires nonempty `clarificationRefs` linking that fact "
+            "to actual C-NNN records, including answered records; `technical-verification` "
+            "requires no user question. Preserve the fact, whyItMatters, and evidence. "
+            "Historical unclassified facts remain readable but require classification "
+            "before blocked report reassembly. Saving does not lift blocked routing."),
+            ("After a linked decision is answered, preserve its disposition and selected "
+            "value. Update humanSummary.actions, verdictCard.nextStep, and selection "
+            "guidance to name remaining technical verification separately from unanswered "
+            "user decisions; never reopen an answered question to permit saving."),
             "Each `feasibilityVotes` row states that analyser's own verdict, "
             "rationale, and strongest counterevidence as its result gives them. "
             "Two non-`uncertain` votes with identical rationale and "
@@ -282,7 +303,6 @@ class ReportSynthesisPacket:
                     "user response carry-in",
                 ],
                 "validationRules": [
-                    "source-digest-match",
                     "writer-owned-fields-only",
                     "all-defects-collected",
                     *self._carry_validation_rules(),
@@ -307,7 +327,7 @@ class ReportSynthesisPacket:
             "- 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",
+            "- Validation: writer-owned fields, all defects collected",
         ]
         # 작성자가 실제로 읽는 것은 마크다운이다. JSON 정본에만 실으면 지시가
         # 도달하지 않는다.
@@ -315,9 +335,14 @@ 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())
-        for source in self.sources:
-            lines.extend(_source_markdown(source, self.task_type, self.sources))
-        return "\n".join(lines).rstrip() + "\n"
+        sections = [("Authoring Contract", "\n".join(lines[1:]).rstrip() + "\n")]
+        sections.extend(
+            (source.label, "\n".join(_source_markdown(
+                source, self.task_type, self.sources,
+            )).rstrip() + "\n")
+            for source in self.sources
+        )
+        return _indexed_markdown(lines[0], sections)
 
 
 _SOURCE_FIELDS = (
@@ -333,12 +358,156 @@ _SOURCE_FIELDS = (
 )
 
 
+_READ_CHUNK_BYTES = 16_000
+_SHARED_TEXT_MIN_BYTES = 256
+_ANALYSER_OPERATION_SECTIONS = frozenset({
+    "Required workers", "Optional workers", "Team contract",
+    "Worker interaction model", "Tooling — read-only MCP availability",
+    "Run-scoped worker-resource lifecycle",
+})
+
+
+def _indexed_markdown(title: str, sections: list[tuple[str, str]]) -> str:
+    """긴 한 줄과 다중 바이트 문자도 손실 없이 나눌 읽기 위치를 싣는다."""
+    ranges: list[tuple[str, int, int]] = []
+    offset = 0
+    for label, content in sections:
+        raw = content.encode("utf-8")
+        start = 0
+        while start < len(raw):
+            end = min(start + _READ_CHUNK_BYTES, len(raw))
+            while end < len(raw) and raw[end] & 0xC0 == 0x80:
+                end -= 1
+            ranges.append((label, offset + start, end - start))
+            start = end
+        offset += len(raw)
+    prefix = f"{title}\n\n## Read Index\n\n"
+    prefix += (
+        "Read every range once, in order. Offsets are zero-based UTF-8 bytes "
+        "in this Markdown file; each range is at most 16000 bytes. Use "
+        "`dd if='<packet-path>' bs=1 skip=<start> count=<bytes> 2>/dev/null`. "
+        "Continue with the next range after a successful read; do not reread "
+        "the beginning. Source paths identify originals; the sibling "
+        "`.data.json` retains every frozen source verbatim.\n\n"
+        "| Source | Start byte | Bytes |\n|---|---:|---:|\n"
+    )
+    prefix_size = 0
+    while True:
+        index = prefix + "".join(
+            f"| {label.replace('|', '/')} | {start + prefix_size} | {size} |\n"
+            for label, start, size in ranges
+        ) + "\n<!-- END READ INDEX -->\n"
+        size = len(index.encode("utf-8"))
+        if size == prefix_size:
+            break
+        prefix_size = size
+    return index + "".join(content for _, content in sections)
+
+
+def _writer_profile_view(content: str) -> str:
+    """저작 규칙과 미지 절을 유지하고 분석자 배치 절만 참조로 바꾼다."""
+    lines: list[str] = []
+    skipping = False
+    fence = ""
+    for number, line in enumerate(content.splitlines(), 1):
+        marker = re.match(r"^\s*(`{3,}|~{3,})", line)
+        if marker:
+            token = marker.group(1)
+            if not fence:
+                fence = token
+            elif token[0] == fence[0] and len(token) >= len(fence):
+                fence = ""
+        if not fence and line.startswith("- "):
+            label = line[2:].split(":", 1)[0].split(" (", 1)[0].strip("*")
+            skipping = label in _ANALYSER_OPERATION_SECTIONS
+            if skipping:
+                lines.append(f"- {label}: analyser operation; original source line {number}.")
+        elif not fence and line.startswith("#"):
+            skipping = False
+        if not skipping:
+            lines.append(line)
+    return "\n".join(lines)
+
+
+def _replace_shared_text(value: Any, references: Mapping[str, str]) -> Any:
+    if isinstance(value, str):
+        return {"$sharedText": references[value]} if value in references else value
+    if isinstance(value, list):
+        return [_replace_shared_text(item, references) for item in value]
+    if isinstance(value, dict):
+        return {key: _replace_shared_text(item, references) for key, item in value.items()}
+    return value
+
+
+def _convergence_view(content: str) -> str:
+    """반복된 근거 문자열만 공유하고 모든 회차·표·미지 필드는 유지한다."""
+    try:
+        state = json.loads(content)
+    except json.JSONDecodeError:
+        return content
+    counts: Counter[str] = Counter()
+    pending = [state]
+    while pending:
+        value = pending.pop()
+        if isinstance(value, dict):
+            # 원자료의 같은 모양과 새 참조를 혼동하지 않는다.
+            if "$sharedText" in value:
+                return content
+            pending.extend(value.values())
+        elif isinstance(value, list):
+            pending.extend(value)
+        elif isinstance(value, str) and len(value.encode("utf-8")) >= _SHARED_TEXT_MIN_BYTES:
+            counts[value] += 1
+    repeated = sorted(text for text, count in counts.items() if count > 1)
+    if not repeated:
+        return content
+    references = {text: f"T{index}" for index, text in enumerate(repeated, 1)}
+    view = {
+        "sharedText": {ref: text for text, ref in references.items()},
+        "state": _replace_shared_text(state, references),
+    }
+    return json.dumps(view, ensure_ascii=False, indent=1)
+
+
+def _writer_schema_view(content: str, task_type: str) -> tuple[str, list[str]]:
+    try:
+        schema = json.loads(content)
+    except json.JSONDecodeError:
+        return content, ["- View: schema is not JSON; the original text is retained."]
+    if not isinstance(schema, dict) or not schema.get("properties"):
+        return content, []
+    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)
+    return json.dumps(excerpt, ensure_ascii=False, indent=1), [
+        "- View: writer-owned schema excerpt. Task-specific requirements are listed above.",
+    ]
+
+
 def _source_markdown(
     source: ReportSynthesisSource, task_type: str,
     sources: tuple[ReportSynthesisSource, ...],
 ) -> list[str]:
     content = source.content.rstrip("\n")
     view = []
+    if source.label == "Analysis profile":
+        content = _writer_profile_view(content)
+    if source.label == "Analysis material":
+        brief = next((item.content.strip() for item in sources if item.label == "Task brief"), "")
+        if len(brief.encode("utf-8")) >= _SHARED_TEXT_MIN_BYTES:
+            content = content.replace(brief, 'Read the complete "Source: Task brief" above.')
+    if source.label == "Convergence state":
+        content = _convergence_view(content)
+        if content != source.content.rstrip("\n"):
+            view = [
+                "- View: lossless shared-text references. Replace each "
+                '`{"$sharedText":"Tn"}` with `sharedText.Tn` when reading `state`. '
+                "Every finding, vote, round, condition, dissent, and unknown field remains.",
+            ]
     if source.label == "Analysis packet":
         texts = {item.label: item.content for item in sources}
         content = reference_source_extracts(
@@ -351,32 +520,10 @@ def _source_markdown(
         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.",
+                "the original line index is omitted.",
             ]
     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.",
-            ]
+        content, view = _writer_schema_view(content, task_type)
     longest = max((len(run) for run in re.findall(r"`+", content)), default=0)
     fence = "`" * max(3, longest + 1)
     return [
@@ -385,7 +532,6 @@ def _source_markdown(
         "",
         f"- Owner: `{source.owner}`",
         f"- Path: `{source.path}`",
-        f"- Digest: `{source.digest}`",
         *view,
         "",
         f"{fence}text",
@@ -628,7 +774,7 @@ def _attempt_result_specs(
 
 
 def _accounting_snapshot(team_state: Mapping[str, Any]) -> dict[str, Any]:
-    workers = team_state.get("workers")
+    workers = accounting_workers(team_state)
     worker_usage = []
     if isinstance(workers, list):
         worker_usage = [
@@ -700,13 +846,11 @@ def _read_sources(
         except (OSError, UnicodeError) as exc:
             issues.append(ReportSynthesisPacketIssue(owner, label, path, str(exc)))
             continue
-        digest = "sha256:" + hashlib.sha256(content.encode("utf-8")).hexdigest()
         sources.append(
             ReportSynthesisSource(
                 label=label,
                 owner=owner,
                 path=_relative(project_root, path),
-                digest=digest,
                 content=content,
             )
         )
@@ -929,18 +1073,8 @@ def verify_report_synthesis_packet_sources(
             )
             continue
         try:
-            content = path.read_text(encoding="utf-8")
+            path.read_text(encoding="utf-8")
         except (OSError, UnicodeError) as exc:
             issues.append(ReportSynthesisPacketIssue(owner, label, path, str(exc)))
             continue
-        digest = "sha256:" + hashlib.sha256(content.encode("utf-8")).hexdigest()
-        if digest != source.get("digest"):
-            issues.append(
-                ReportSynthesisPacketIssue(
-                    owner,
-                    label,
-                    path,
-                    "source value changed after packet materialization",
-                )
-            )
     return tuple(issues)

package/runtime/python/okstra_ctl/run.py

@@ -14,6 +14,11 @@ state passing, and are read once at the start.
 """
 from __future__ import annotations
 
+from .technical_verification import (
+    resolve_technical_verification_input,
+    write_technical_verification_input,
+)
+
 import hashlib
 from argparse import (
     Action,
@@ -529,6 +534,7 @@ class PrepareInputs:
     brief_path: Path  # absolute, already resolved
     analysis_target: str = ""
     evidence_inputs_raw: str = ""
+    user_authorization_json: str = ""
     directive: str = ""
     workers_override: str = ""
     role_counts_raw: tuple[str, ...] = ()
@@ -1175,6 +1181,7 @@ def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
         ),
         ("--critic", inp.critic or legacy_fallbacks.get("CRITIC_CHOICE", "")),
         ("--related-tasks", inp.related_tasks_raw),
+        ("--user-authorization-json", inp.user_authorization_json),
         ("--work-category", inp.work_category),
     ]
     argv: list[str] = []
@@ -3819,6 +3826,18 @@ def _write_instruction_set_sources(
             json.loads(ctx.get("RELATED_TASKS_JSON", "[]")),
         ),
     )
+    if inp.task_type == "technical-verification":
+        verification_path = write_technical_verification_input(
+            json.loads(ctx["TECHNICAL_VERIFICATION_INPUT_JSON"]),
+            Path(ctx["RUN_DIR"]), ctx["RUN_MANIFESTS_SEQ"],
+        )
+        packet += (
+            "\n## Technical Verification Input\n\n"
+            f"- Frozen input: `{verification_path}`\n"
+            f"- Experiment copies only: `{ctx['RUN_DIR']}/experiments/{ctx['RUN_MANIFESTS_SEQ']}/<worker-id>/`\n"
+            "- Read the input before planning experiments; copy each fact identity verbatim into results.\n"
+            + "\n```json\n" + ctx["TECHNICAL_VERIFICATION_INPUT_JSON"] + "\n```\n"
+        )
     if inp.task_type in ANALYSIS_TASK_TYPES:
         packet += (
             "\n## Analysis Evidence\n\n"
@@ -4662,8 +4681,54 @@ def _title_lead_pane(inp: PrepareInputs) -> None:
         print(f"okstra: lead pane title not applied — {reason}", file=sys.stderr)
 
 
+def _prepare_user_authorization(inp: PrepareInputs) -> dict:
+    """승인 기록은 해당 실행 입력과 일치할 때만 전달하며 호스트 권한을 부여하지 않는다."""
+    if not inp.user_authorization_json:
+        return {}
+    try:
+        record = json.loads(inp.user_authorization_json)
+    except (TypeError, ValueError) as exc:
+        raise PrepareError("invalid user authorization JSON") from exc
+    if not isinstance(record, dict) or (
+        record.get("schemaVersion") != "1.0"
+        or record.get("source") != "wizard-confirmation"
+        or record.get("response") != "proceed"
+        or not isinstance(record.get("prompt"), str)
+        or not record["prompt"].strip()
+        or not isinstance(record.get("scope"), dict)
+    ):
+        raise PrepareError("user authorization requires the displayed prompt, proceed response, and scope")
+    if inp.task_type == "implementation":
+        stages = record.get("stageScope") or [record["scope"].get("stage")]
+        if not isinstance(stages, list) or inp.stage not in stages:
+            raise PrepareError("user authorization scope does not include --stage; confirm the changed scope")
+    expected = {
+        "project-root": str(inp.project_root), "project-id": inp.project_id,
+        "task-group": inp.task_group, "task-id": inp.task_id, "task-type": inp.task_type,
+        "role-model": list(inp.role_models_raw), "role-count": list(inp.role_counts_raw),
+        "directive": inp.directive, "related-tasks": inp.related_tasks_raw,
+        "analysis-target": inp.analysis_target, "evidence-inputs": inp.evidence_inputs_raw,
+    }
+    for key, value in expected.items():
+        if record["scope"].get(key) != value:
+            raise PrepareError(f"user authorization scope does not match --{key}; confirm the changed scope")
+    for key, path in (
+        ("task-brief", inp.brief_path if inp.task_type != "release-handoff" else ""),
+        ("approved-plan", inp.approved_plan_path),
+        ("clarification-response", inp.clarification_response_path),
+        ("selected-direction", inp.selected_direction_path),
+    ):
+        recorded = record["scope"].get(key, "")
+        if not isinstance(recorded, str) or bool(recorded) != bool(path) or (
+            recorded and (inp.project_root / recorded).resolve() != (inp.project_root / path).resolve()
+        ):
+            raise PrepareError(f"user authorization scope does not match --{key}; confirm the changed scope")
+    return record
+
+
 def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     """Produce a complete okstra task bundle on disk. See module docstring."""
+    user_authorization = _prepare_user_authorization(inp)
     workspace_root = Path(inp.workspace_root)
     project_root = Path(inp.project_root)
     lead_runtime = _normalize_lead_runtime(inp.lead_runtime)
@@ -4709,6 +4774,19 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         )
     _validate_group_context_preflight(project_root, inp.task_group)
     selected_direction = _resolve_planning_direction(inp)
+    technical_input = None
+    from .paths import task_dir
+    if inp.task_type == "technical-verification":
+        if not inp.clarification_response_path:
+            raise PrepareError("technical-verification requires --clarification-response pointing to this task's option-selection record")
+        try:
+            technical_input = resolve_technical_verification_input(
+                Path(inp.clarification_response_path), project_root,
+                task_dir(project_root, inp.task_group, inp.task_id),
+                f"{inp.project_id}:{inp.task_group}:{inp.task_id}",
+            )
+        except ValueError as exc:
+            raise PrepareError(str(exc)) from exc
     if inp.task_type == "implementation":
         ctx_stage_map = _prepare_implementation_approved_plan(inp)
 
@@ -4871,6 +4949,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         relative_to_project_root(Path(inp.clarification_response_path), project_root)
         if inp.clarification_response_path else ""
     )
+    ctx["TECHNICAL_VERIFICATION_INPUT_JSON"] = json.dumps(technical_input) if technical_input else ""
     selected_direction_relative = (
         relative_to_project_root(Path(inp.selected_direction_path), project_root)
         if inp.selected_direction_path else ""
@@ -4888,6 +4967,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "RECOMMENDED_ANALYSERS": selected_reviewers,
         "HOST_RUNTIME": lead_runtime,
         "LEAD_RUNTIME": lead_runtime,
+        "USER_AUTHORIZATION_JSON": json.dumps(user_authorization, ensure_ascii=False),
         "LEAD_RUNTIME_REQUEST": lead_runtime_request,
         "RUNTIME_RESOLUTION_JSON": runtime_resolution_json or "{}",
         "PR_TEMPLATE_PATH": pr_template_path_str,
@@ -5107,6 +5187,7 @@ def build_prepare_argument_parser():
         ),
     )
     p.add_argument("--directive", default="")
+    p.add_argument("--user-authorization-json", default="")
     p.add_argument("--analysis-target", default="", dest="analysis_target")
     p.add_argument("--evidence-inputs", default="", dest="evidence_inputs_raw")
     p.add_argument(
@@ -5392,6 +5473,7 @@ def main(argv: list[str]) -> int:
         analysis_target=args.analysis_target,
         evidence_inputs_raw=args.evidence_inputs_raw,
         directive=args.directive,
+        user_authorization_json=args.user_authorization_json,
         workers_override=args.workers_override,
         role_counts_raw=tuple(args.role_counts_raw),
         role_models_raw=tuple(args.role_models_raw),

package/runtime/python/okstra_ctl/team.py

@@ -125,7 +125,10 @@ def _add_await_parser(sub) -> None:
     _add_run_args(parser)
     parser.add_argument("--poll-interval-seconds", type=int, default=5)
     parser.add_argument("--timeout-seconds", type=int, default=None)
-    parser.add_argument("--heartbeat-seconds", type=int, default=30)
+    parser.add_argument(
+        "--heartbeat-seconds", type=int, default=30,
+        help="minimum interval between changed pending-attempt summaries; 0 disables output",
+    )
     parser.add_argument("--json", action="store_true")