okstra 0.214.1 → 0.216.0

package/runtime/python/okstra_ctl/manager_launch.py

@@ -5,6 +5,9 @@ import shlex
 from pathlib import Path
 
 from okstra_ctl.jsonl import append_jsonl, read_jsonl
+from okstra_ctl.phases.discussion.followup import RECOMMENDED_PHASE as DISCUSSION_FOLLOW_UP_PHASE
+from okstra_ctl.phases.discussion.followup import brief_revision_ref
+from okstra_ctl.phases.discussion.store import same_task
 
 from .manager_paths import (
     MANAGER_CONTEXT_DIRECTIVE_PREFIX,
@@ -91,6 +94,24 @@ def _sibling_snapshots(snapshot: dict, target_task_key: str) -> list[dict]:
     ]
 
 
+def _discussion_follow_up_brief(snapshot: dict, target_task_key: str) -> Path | None:
+    """`okstra discussion follow-up-brief` 가 이 하위 task 에 쓴 브리프.
+
+    그 명령은 manager 상태에 쓰지 않는다(관리자 없는 토론도 있다). 같은 manager task 에 묶인
+    토론의 마지막 sync 가 남긴 연결에서 위치만 찾고, 고정한 확정본은 실행 시점에 브리프에서 다시 읽는다.
+    """
+    for row in snapshot.get("children", []):
+        discussion = row.get("discussion") if isinstance(row, dict) else None
+        follow_ups = discussion.get("followUps") if isinstance(discussion, dict) else None
+        for link in (follow_ups or {}).get("items") or []:
+            if not same_task(str(link.get("targetTaskKey") or ""), target_task_key):
+                continue
+            candidate = Path(str(link.get("targetProjectRoot") or "")) / str(link.get("briefPath") or "")
+            if candidate.is_file() and brief_revision_ref(candidate) is not None:
+                return candidate
+    return None
+
+
 def _render_context(
     *,
     manifest: dict,
@@ -98,6 +119,7 @@ def _render_context(
     child_task_key: str,
     directives: list[dict],
     siblings: list[dict],
+    discussion_ref: dict | None,
 ) -> str:
     lines = [
         "# Okstra Manager Child Context",
@@ -123,6 +145,14 @@ def _render_context(
                       f"- brief: {child.get('briefPath') or ''}", ""])
         lines.extend(f"- in scope: {item}" for item in child["scope"])
         lines.append("")
+    if discussion_ref:
+        lines.extend(["## Discussion Revision", "",
+                      f"- discussion: {discussion_ref['discussionTaskKey']}",
+                      f"- revision: {discussion_ref['revisionId']} ({discussion_ref['contentDigest']})",
+                      f"- follow-up: {discussion_ref['followUp']}",
+                      f"- requirements: {', '.join(discussion_ref['requirementIds'])}",
+                      "- The brief pins this revision; a newer revision applies only when the user adopts it.",
+                      ""])
     lines.extend(["## Manager Directives", ""])
     for row in directives:
         lines.append(f"- [{row.get('scope')}] {row.get('body')}")
@@ -186,6 +216,8 @@ def _record_launch_prepared(
             "workerDispatchBackend": WORKER_DISPATCH_BACKEND,
             "contextPath": packet["contextPath"],
             "runArgs": packet["runArgs"],
+            **({"discussionRevisionRef": packet["discussionRevisionRef"]}
+               if "discussionRevisionRef" in packet else {}),
         },
     )
 
@@ -213,6 +245,9 @@ def build_launch_packet(
     _validate_child_task_key(child, target_task_key)
     project_root = _validated_project_root(project)
     created_at = now or _now_iso()
+    brief_path = (Path(str(child["briefPath"])) if child.get("briefPath")
+                  else _discussion_follow_up_brief(snapshot, target_task_key))
+    discussion_ref = brief_revision_ref(brief_path) if brief_path is not None and brief_path.is_file() else None
     context_path = child_context_path(home, manager_id, task_group, task_id, project_id, child_task_id_value)
     context_path.parent.mkdir(parents=True, exist_ok=True)
     context_path.write_text(
@@ -222,6 +257,7 @@ def build_launch_packet(
             child_task_key=target_task_key,
             directives=_directives_for_project(directives, project_id),
             siblings=_sibling_snapshots(snapshot, target_task_key),
+            discussion_ref=discussion_ref,
         ),
         encoding="utf-8",
     )
@@ -239,10 +275,12 @@ def build_launch_packet(
     # `task split` 이 기록한 브리프·권장 phase 를 넘겨 런처가 첫 실행에서 다시 묻지 않게 한다.
     # phase 는 하위 태스크가 아직 없을 때만 넘긴다. 이미 있으면 런처가 manifest 에서 다음
     # phase 를 채워야 하는데, 두 값이 다 주어지면 그 채우기를 건너뛴다(autofill_from_manifest).
-    if child.get("recommendedPhase") and _resolve_task_root_read_only(Path(project_root), target_task_key) is None:
-        run_args.extend(["--task-type", str(child["recommendedPhase"])])
-    if child.get("briefPath"):
-        run_args.extend(["--task-brief", str(child["briefPath"])])
+    # 토론 후속 브리프는 권장 phase 를 따로 적지 않아도 requirements-discovery 에서 시작한다.
+    recommended = child.get("recommendedPhase") or (DISCUSSION_FOLLOW_UP_PHASE if discussion_ref else "")
+    if recommended and _resolve_task_root_read_only(Path(project_root), target_task_key) is None:
+        run_args.extend(["--task-type", str(recommended)])
+    if brief_path is not None:
+        run_args.extend(["--task-brief", str(brief_path)])
     run_args += [
         "--directive",
         f"{MANAGER_CONTEXT_DIRECTIVE_PREFIX}{context_path}",
@@ -262,6 +300,8 @@ def build_launch_packet(
         "shellCommand": shlex.join([command, *run_args]),
         "createdAt": created_at,
     }
+    if discussion_ref:
+        packet["discussionRevisionRef"] = discussion_ref
     _record_launch_prepared(
         home=home,
         manager_id=manager_id,

package/runtime/python/okstra_ctl/manager_sync.py

@@ -7,6 +7,8 @@ from okstra_project import TASKS_RELATIVE, StateError, parse_task_key, read_task
 
 from . import next_phase
 from .next_phase import STATUS_BLOCKED, STATUS_TERMINAL
+from .phases.discussion.overview import discussion_overview
+from .phases.discussion.store import DiscussionStore
 from .manager_paths import children_json_path, projects_json_path, snapshots_json_path, task_manifest_path
 from .manager_store import _now_iso, _read_json, _read_json_default, _write_json
 
@@ -54,6 +56,9 @@ def _resolve_task_root_read_only(project_root: Path, task_key: str) -> Path | No
     return None
 
 
+DISCUSSION_TASK_TYPE = "discussion"
+
+
 def _base_child_snapshot(child: dict) -> dict:
     task_key = str(child.get("taskKey") or "")
     return {
@@ -78,6 +83,10 @@ def _snapshot_child(project_root: Path, child: dict) -> dict:
         return {**base, "error": str(exc)}
     workflow = _workflow(manifest)
     outcome = _phase_outcome(manifest)
+    discussion = (
+        {"discussion": discussion_overview(DiscussionStore(project_root, task_key))}
+        if manifest.get("taskType") == DISCUSSION_TASK_TYPE else {}
+    )
     return {
         **base,
         "exists": True,
@@ -96,6 +105,7 @@ def _snapshot_child(project_root: Path, child: dict) -> dict:
         "crossProjectDependencies": _list_field(outcome, "crossProjectDependencies"),
         "recommendedNextSteps": _list_field(outcome, "recommendedNextSteps"),
         "openClarifications": _list_field(outcome, "openClarifications"),
+        **discussion,
     }
 
 
@@ -147,6 +157,9 @@ def summary_bucket(row: dict) -> str:
     """스냅샷이 있는 하위 task 한 줄을 요약 칸 하나로 분류한다."""
     if not row.get("exists", False):
         return "missing"
+    # 토론 완료는 후속 작업이나 프로젝트의 완료가 아니다 — 토론 task 는 따로 센다.
+    if row.get("taskType") == DISCUSSION_TASK_TYPE:
+        return "discussion"
     work_status = str(row.get("workStatus") or "")
     if work_status in _WORK_STATUS_BUCKETS:
         return _WORK_STATUS_BUCKETS[work_status]
@@ -162,7 +175,7 @@ def status_task(home: Path, manager_id: str, task_group: str, task_id: str) -> d
     by_key = {row.get("taskKey"): row for row in snapshot.get("children", []) if isinstance(row, dict)}
     linked = _project_map(home, manager_id)
     rows = []
-    summary = {"planned": 0, "missing": 0, "running": 0, "done": 0, "blocked": 0}
+    summary = {"planned": 0, "missing": 0, "running": 0, "done": 0, "blocked": 0, "discussion": 0}
     for child in children.get("children", []):
         if not isinstance(child, dict):
             continue

package/runtime/python/okstra_ctl/manager_view.py

@@ -22,7 +22,7 @@ from .paths import find_asset_root
 
 TEMPLATE_RELATIVE = ("templates", "manager", "view.template.html")
 _MARKER = re.compile(r"\{\{([A-Z]+)\}\}")
-BUCKETS = ("planned", "missing", "running", "done", "blocked")
+BUCKETS = ("planned", "missing", "running", "done", "blocked", "discussion")
 
 
 def _now_iso() -> str:
@@ -90,6 +90,54 @@ def _projects_table(projects: list[dict]) -> str:
     return f'<div class="projects">{table}</div>'
 
 
+def _discussion_fields(discussion: dict) -> tuple[tuple[str, str], ...]:
+    if discussion.get("state") == "unknown":
+        return (("Discussion", "unknown"),)
+    questions = discussion.get("pendingQuestions") or {}
+    state = discussion.get("completedRevision") if discussion.get("state") == "completed" else (
+        f"draft ({discussion.get('phase') or '-'})")
+    return (
+        ("Discussion", state or "-"),
+        ("Pending questions", f"{len(questions.get('forUser') or [])} for the user · "
+                              f"{len(questions.get('forParticipants') or [])} for participants"),
+    )
+
+
+def _discussion_detail(discussion: dict) -> str:
+    """토론 원본의 식별자·상태만 보여 준다. 마지막 sync 시점의 값이다."""
+    if discussion.get("state") == "unknown":
+        return f'<p class="child-error"><strong>Discussion unknown:</strong> {_e(discussion.get("reason"))}</p>'
+    questions = discussion.get("pendingQuestions") or {}
+    pending = [f"{_e(row.get('recordId'))} → user: {_e(row.get('text'))}" for row in questions.get("forUser") or []]
+    pending += [f"{_e(row.get('recordId'))} → {_e(row.get('to'))}: {_e(row.get('text'))}"
+                for row in questions.get("forParticipants") or []]
+    revisions = [
+        f"<code>{_e(row.get('revisionId'))}</code> · "
+        + (f"unknown — {_e(row.get('reason'))}" if row.get("state") == "unknown"
+           else f"change reason: {_e(row.get('changeReason'))}" if row.get("changeReason") else "first revision")
+        for row in discussion.get("revisions") or []
+    ]
+    reopened = discussion.get("reopenedFrom")
+    if reopened:
+        revisions.append(f"re-discussing <code>{_e(reopened.get('revisionId'))}</code>: {_e(reopened.get('reason'))}")
+    links = discussion.get("followUps") or {}
+    follow_ups = [
+        f"<code>{_e(row.get('targetTaskKey'))}</code> ({_e(row.get('followUp'))}) · {_e(row.get('state'))} · "
+        f"uses {_e(row.get('pinnedRevision') or '-')}"
+        + (f" · {_e(row.get('reason'))}" if row.get("reason") else "")
+        for row in links.get("items") or []
+    ]
+    follow_ups += [f"{_e(label)} · not linked" for label in links.get("unlinked") or []]
+    if links.get("state") == "unknown":
+        follow_ups = [f"unknown — {_e(links.get('reason'))}"]
+    sections = (("Pending questions", pending), ("Revisions", revisions), ("Follow-ups", follow_ups))
+    body = "".join(
+        f"<dt>{_e(label)}</dt><dd>" + ("<br>".join(items) if items else "-") + "</dd>"
+        for label, items in sections
+    )
+    return f'<dl class="child-status">{body}</dl>'
+
+
 def _child_rows(children: list[dict], roots: dict[str, str]) -> list[list[str]]:
     rows = []
     for child in children:
@@ -105,6 +153,9 @@ def _child_rows(children: list[dict], roots: dict[str, str]) -> list[list[str]]:
             ("Verdict", child.get("finalVerdict") or "-"),
             ("Launch", launch.get("status") or "-"),
         )
+        discussion = child.get("discussion") if isinstance(child.get("discussion"), dict) else None
+        if discussion is not None:
+            status_fields += _discussion_fields(discussion)
         status = "".join(f"<dt>{_e(label)}</dt><dd>{_e(value)}</dd>" for label, value in status_fields)
         links = "".join(
             _file_link(root, str(path), label)
@@ -122,6 +173,7 @@ def _child_rows(children: list[dict], roots: dict[str, str]) -> list[list[str]]:
                 + ("" if child.get("projectLinked", True) else " " + _chip("unlinked")),
                 _chip(str(child.get("summaryBucket") or "planned")) + f'<dl class="child-status">{status}</dl>',
                 f'<div class="child-assignment">{_e(assignment or "-")}</div>'
+                + (_discussion_detail(discussion) if discussion is not None else "")
                 + error + (f'<div class="child-links">{links}</div>' if links else ""),
             ]
         )

package/runtime/python/okstra_ctl/next_phase.py

@@ -45,6 +45,7 @@ _SIDETRACK_TASK_TYPES = frozenset(
         "project-analysis",
         "feature-analysis",
         "change-impact-analysis",
+        "discussion",
     }
 )
 

package/runtime/python/okstra_ctl/phases/catalog.py

@@ -1,4 +1,4 @@
-"""12개 작업 유형과 단계 디렉터리의 고정 대응.
+"""13개 작업 유형과 단계 디렉터리의 고정 대응.
 
 이 모듈을 import 해도 단계 실행 모듈은 적재되지 않는다. 경로는 문자열로만
 계산한다. 외부 설정에서 모듈 경로를 받아 실행하지 않는다.
@@ -68,6 +68,7 @@ PHASES: tuple[PhaseRecord, ...] = (
     _record("implementation", "implementation", True, "build_implementation_view"),
     _record("final-verification", "final_verification", True, "build_final_verification_view"),
     _record("release-handoff", "release_handoff", True, "build_release_handoff_view"),
+    _record("discussion", "discussion", True, "build_discussion_view"),
 )
 
 _BY_TASK_TYPE = {row.task_type: row for row in PHASES}

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

@@ -0,0 +1 @@
+"""토론 단계의 역할 구성과 출력 경계."""

package/runtime/python/okstra_ctl/phases/discussion/boundary.json

@@ -0,0 +1,11 @@
+{
+  "allowed": "  - research of the discussion subject with evidence, assumptions and alternative directions\n  - adversarial cross-checking of factual claims between participants\n  - questions put to the user one at a time, and the user's answers and decisions recorded as user decisions\n  - remaining disagreements, risks and unverified scope presented for the user's choice\n  - confirmed requirements, scope, exclusions and implementation direction once the user confirms completion",
+  "forbidden": [
+    "source code edits of any kind",
+    "detailed implementation plans, file-change specifications or stage maps — those belong to a follow-up task",
+    "executing builds, migrations, deployments, or any state-mutating command",
+    "treating agent consensus, a convergence stop or a finished worker batch as the user's completion confirmation",
+    "deciding the user's intent or priority from a fact check",
+    "starting a follow-up task's run or any other lifecycle phase inside this run, or editing a follow-up task's plan or source"
+  ]
+}