okstra 0.214.1 → 0.216.0

package/runtime/python/okstra_ctl/phases/discussion/validation.py

@@ -0,0 +1,111 @@
+"""토론 완료 검사 — 완료 확인 전 초안의 빠진 항목, 그리고 발행된 확정본의 필수 내용."""
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+_REDUCED_CHOICES = ("reduce",)
+
+
+def completion_errors(draft: Mapping[str, Any], direction: str, risk_acknowledgement: str) -> list[str]:
+    errors: list[str] = []
+    if draft["subject"] is None:
+        errors.append("the subject and the question are not confirmed (`okstra discussion confirm-subject`)")
+    if not direction.strip():
+        errors.append("the user's direction choice is empty (--direction)")
+    if not risk_acknowledgement.strip():
+        errors.append("the user's confirmation of the remaining disagreements and risks is empty (--risk)")
+    if not draft["requirements"]:
+        errors.append("no requirement is recorded for this draft (`okstra discussion add-requirement`)")
+    kinds = {row["scopeKind"] for row in draft["scope"]}
+    for kind in ("in-scope", "excluded"):
+        if kind not in kinds:
+            errors.append(
+                f"no `{kind}` entry is recorded for this draft (`okstra discussion add-scope --kind {kind}`); "
+                "record an explicit entry even when it is `none`"
+            )
+    cycles = draft["cycles"]
+    if not any(cycle["status"] == "closed" for cycle in cycles):
+        errors.append("no research cycle has closed; the revision would carry no evidence")
+    if cycles and cycles[-1]["status"] == "open":
+        errors.append(f"research cycle {cycles[-1]['recordId']} is still open; settle and close it first")
+    if cycles and cycles[-1]["status"] == "superseded":
+        errors.append(
+            f"the user chose to replace a participant of {cycles[-1]['recordId']}; "
+            "the replacement run has not closed its cycle"
+        )
+    if draft["unrecoveredFailures"]:
+        errors.append(
+            f"{', '.join(draft['unrecoveredFailures'])} wait for the user's choice (`okstra discussion recover`)"
+        )
+    if draft["pendingForUser"]:
+        errors.append(f"{', '.join(draft['pendingForUser'])} still wait for the user's answer")
+    if draft["pendingForParticipants"]:
+        errors.append(f"{', '.join(draft['pendingForParticipants'])} still wait for a participant's answer")
+    return errors
+
+
+def _missing(revision: Mapping[str, Any], path: str) -> bool:
+    node: Any = revision
+    for part in path.split("."):
+        if not isinstance(node, Mapping) or part not in node:
+            return True
+        node = node[part]
+    return node is None or node == "" or node == []
+
+
+_REQUIRED = (
+    "revisionId",
+    "taskKey",
+    "subject.subject",
+    "subject.question",
+    "confirmation.recordId",
+    "confirmation.draftVersion",
+    "confirmation.riskAcknowledgement",
+    "direction",
+    "requirements",
+    "scope.inScope",
+    "scope.excluded",
+    "participants.cycles",
+)
+_LISTS = ("startInputs", "decisions", "evidence", "disagreements", "unverified", "participants.failures",
+          "itemChanges.carried", "itemChanges.added", "itemChanges.withdrawn")
+
+
+def revision_errors(revision: Mapping[str, Any]) -> list[str]:
+    """확정본이 설계가 정한 내용을 빠짐없이, 서로 어긋나지 않게 싣는가."""
+    errors = [f"`{path}` is missing or empty" for path in _REQUIRED if _missing(revision, path)]
+    for path in _LISTS:
+        node: Any = revision
+        for part in path.split("."):
+            node = node.get(part) if isinstance(node, Mapping) else None
+        if not isinstance(node, list):
+            errors.append(f"`{path}` must be a list")
+    if errors:
+        return errors
+    evidence = {row["recordId"] for row in revision["evidence"]}
+    errors += [
+        f"disagreement {row['recordId']} is not among the evidence claims"
+        for row in revision["disagreements"] if row["recordId"] not in evidence
+    ]
+    reduced = [
+        row for row in revision["participants"]["failures"]
+        if (row.get("recovery") or {}).get("choice") in _REDUCED_CHOICES
+    ]
+    if bool(reduced) != revision["participants"].get("reducedRoster"):
+        errors.append("`participants.reducedRoster` disagrees with the recorded failure choices")
+    unverified = {row.get("recordId") for row in revision["unverified"]}
+    errors += [
+        f"failure {row['recordId']} left its scope unverified but is not listed under `unverified`"
+        for row in reduced if row["recordId"] not in unverified
+    ]
+    items = [*revision["requirements"], *revision["scope"]["inScope"], *revision["scope"]["excluded"]]
+    changes = revision["itemChanges"]
+    if sorted(row["recordId"] for row in items) != sorted(
+            row["recordId"] for row in (*changes["carried"], *changes["added"])):
+        errors.append("`itemChanges` carried and added items disagree with the requirements and scope")
+    if changes["carried"] and changes.get("carriedFrom") is None:
+        errors.append("`itemChanges.carried` lists items but names no revision they were carried from")
+    previous = revision.get("previousRevision")
+    if previous is not None and any(_missing(previous, key) for key in ("revisionId", "contentDigest", "changeReason")):
+        errors.append("`previousRevision` must name the revision id, its content digest and the reason for change")
+    return errors

package/runtime/python/okstra_ctl/phases/discussion/wizard.py

@@ -0,0 +1,90 @@
+"""토론 시작 입력 질문 — brief 경로 대신 링크·짧은 설명·이 task 의 토론 이어가기를 받는다."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from okstra_ctl.prepare_error import PrepareError
+from okstra_ctl.wizard.ids import (
+    PICK_TYPE_CUSTOM,
+    S_DISCUSSION_START,
+    S_DISCUSSION_START_PICK,
+)
+from okstra_ctl.wizard.prompts import _opt, _p
+from okstra_ctl.wizard.state import Prompt, WizardError, WizardState
+
+from .entry import classify_start_input
+from .store import DiscussionStore, has_records
+
+_CONTINUE = "__continue__"
+_BRIEF = "__brief__"
+
+
+def _task_key(state: WizardState) -> str:
+    return f"{state.project_id}:{state.task_group}:{state.task_id}"
+
+
+def _has_discussion(state: WizardState) -> bool:
+    return not state.is_new_task and has_records(
+        DiscussionStore(Path(state.project_root), _task_key(state))
+    )
+
+
+def _brief(state: WizardState) -> str:
+    """새 task 는 방금 고른 brief, 기존 task 는 매니페스트에 등록된 brief.
+
+    토론 run 이 등록한 brief 는 prepare 가 만든 입력 문서라 후보가 아니다."""
+    if state.brief_path:
+        return state.brief_path
+    existing = state.existing_brief_path
+    if not existing:
+        return ""
+    generated = DiscussionStore(Path(state.project_root), _task_key(state)).input_path
+    resolved = Path(existing) if Path(existing).is_absolute() else Path(state.project_root) / existing
+    return "" if resolved.resolve() == generated.resolve() else existing
+
+
+def _accept(state: WizardState, value: str) -> str:
+    try:
+        kind, text = classify_start_input(value, Path(state.project_root), _task_key(state))
+    except PrepareError as exc:
+        raise WizardError(str(exc)) from exc
+    state.discussion_start = text
+    state.discussion_start_pending_text = False
+    return f"discussion-start: [{kind}] {text}"
+
+
+def build_discussion_start_pick(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, S_DISCUSSION_START_PICK)
+    options = []
+    if _has_discussion(state):
+        options.append(_opt(_CONTINUE, t["options"][_CONTINUE].format(task_key=_task_key(state)),
+                            recommended=True))
+    brief = _brief(state)
+    if brief:
+        options.append(_opt(_BRIEF, t["options"][_BRIEF].format(brief=brief),
+                            recommended=not options))
+    options.append(_opt(PICK_TYPE_CUSTOM, t["options"][PICK_TYPE_CUSTOM]))
+    return Prompt(step=S_DISCUSSION_START_PICK, kind="pick", label=t["label"],
+                  options=options, echo_template=t["echo_template"])
+
+
+def submit_discussion_start_pick(state: WizardState, value: str) -> Optional[str]:
+    if value == _CONTINUE and _has_discussion(state):
+        return _accept(state, _task_key(state))
+    if value == _BRIEF and _brief(state):
+        return _accept(state, _brief(state))
+    if value == PICK_TYPE_CUSTOM:
+        state.discussion_start_pending_text = True
+        return None
+    raise WizardError(f"expected an offered option or {PICK_TYPE_CUSTOM!r}, got: {value!r}")
+
+
+def build_discussion_start(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, S_DISCUSSION_START)
+    return Prompt(step=S_DISCUSSION_START, kind="text", label=t["label"],
+                  echo_template=t["echo_template"])
+
+
+def submit_discussion_start(state: WizardState, value: str) -> Optional[str]:
+    return _accept(state, value)