okstra 0.214.1 → 0.216.0

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

@@ -0,0 +1,294 @@
+"""확정본별 Memory Book 등록 — 발행과 분리된 동기화 상태.
+
+`<task-root>/discussion/memory/` 아래:
+
+- `revision-NNN.<digest12>.md` — 등록할 요약. 결정·이견·위험·미확인 사항과 확정본 원본 참조만
+  담고 토론 전문은 담지 않는다. 사용자가 고친 요약은 새 digest 의 새 파일이다.
+- `revision-NNN.json` — 그 확정본의 등록 상태(`pending` / `registered` / `refused`)와 시도 이력.
+
+Memory Book 형식의 소유자는 Node 의 `okstra memory add` 다. 여기서는 `--source-key` 로 그 명령을
+부를 뿐 형식을 다시 구현하지 않는다. 출처 키 하나에 기록 하나를 보장하는 것은 Node 쪽 잠금이다.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any, Optional
+
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
+from okstra_ctl.run_context import dir_flock
+
+from .store import (
+    _LOCK_FILENAME,
+    _REVISION_SEPARATOR,
+    DiscussionStore,
+    DiscussionStoreError,
+    _now_iso,
+    _of,
+    _read_records,
+    parse_revision_id,
+    read_revision,
+)
+
+SCHEMA_VERSION = "1.0"
+MEMORY_DIRNAME = "memory"
+SOURCE_KEY_PREFIX = "discussion:"
+PENDING, REGISTERED, REFUSED = "pending", "registered", "refused"
+_TIMEOUT_SECONDS = 60
+_SYNC_HINT = "okstra discussion memory-sync <task-key>"
+
+
+def source_key(revision_id: str) -> str:
+    """확정본 id 는 project-id:task-group:task-id 와 완료 순번이라 프로젝트·작업·확정본을 함께 가리킨다."""
+    return SOURCE_KEY_PREFIX + revision_id
+
+
+def _memory_dir(store: DiscussionStore) -> Path:
+    return store.dir / MEMORY_DIRNAME
+
+
+def _state_path(store: DiscussionStore, sequence: int) -> Path:
+    return _memory_dir(store) / f"revision-{sequence:03d}.json"
+
+
+def _relative(store: DiscussionStore, path: Path) -> str:
+    return path.resolve().relative_to(store.project_root.resolve()).as_posix()
+
+
+def _digest(data: bytes) -> str:
+    return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def _bullets(rows: list[str]) -> list[str]:
+    return [f"- {row}" for row in rows] or ["- none"]
+
+
+def render_summary(revision: dict[str, Any], publication: dict[str, Any]) -> str:
+    task_key = revision["taskKey"]
+    project_id = task_key.split(":", 1)[0]
+    lines = [
+        f"# Discussion outcome {revision['revisionId']}",
+        "",
+        "## Source",
+        "",
+        f"- Revision: `{revision['revisionId']}`",
+        f"- Content digest: `{publication['contentDigest']}`",
+        f"- Revision file: `{publication['revisionPath']}`",
+        f"- Project: `{project_id}`",
+        f"- Task: `{task_key}`",
+        f"- Read it with: `okstra discussion revision-show {task_key} --revision {revision['revisionId']}`",
+        "",
+        "## Subject",
+        "",
+        f"{revision['subject']['subject']} — {revision['subject']['question']}",
+        "",
+        "## Direction",
+        "",
+        revision["direction"],
+        "",
+        "## Decisions",
+        "",
+        *_bullets([f"{row['recordId']}: {row['text']}" for row in revision["decisions"]]),
+        "",
+        "## Disagreements",
+        "",
+        *_bullets([f"{row['recordId']} ({row['standing']}): {row['summary']}" for row in revision["disagreements"]]),
+        "",
+        "## Risks",
+        "",
+        revision["confirmation"]["riskAcknowledgement"],
+        "",
+        "## Unverified",
+        "",
+        *_bullets([f"{row['recordId']} ({row['kind']}): {row['detail']}" for row in revision["unverified"]]),
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def _write_text_atomic(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, raw = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    temporary = Path(raw)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def _summary_path(store: DiscussionStore, sequence: int, digest: str) -> Path:
+    return _memory_dir(store) / f"revision-{sequence:03d}.{digest.split(':', 1)[1][:12]}.md"
+
+
+def _load_state(path: Path) -> Optional[dict[str, Any]]:
+    if not path.is_file():
+        return None
+    try:
+        return load_owned_object(path, artifact="discussion memory state")
+    except JsonBoundaryError as exc:
+        raise DiscussionStoreError(str(exc)) from exc
+
+
+def _save_state(path: Path, state: dict[str, Any]) -> None:
+    try:
+        write_owned_object_atomic(path, state, artifact="discussion memory state")
+    except JsonBoundaryError as exc:
+        raise DiscussionStoreError(str(exc)) from exc
+
+
+def _set_summary(store: DiscussionStore, state: dict[str, Any], sequence: int, text: str, origin: str) -> None:
+    digest = _digest(text.encode("utf-8"))
+    path = _summary_path(store, sequence, digest)
+    _write_text_atomic(path, text)
+    state.update({"summaryPath": _relative(store, path), "summaryDigest": digest, "summaryOrigin": origin})
+
+
+def _prepare_locked(store: DiscussionStore, revision_id: str, summary_text: Optional[str]) -> dict[str, Any]:
+    """요약과 출처를 먼저 기록한다 — 등록이 어디서 끊겨도 같은 키로 다시 부를 근거가 남는다."""
+    _, sequence = parse_revision_id(revision_id)
+    publication, data = read_revision(store, revision_id)
+    path = _state_path(store, sequence)
+    state = _load_state(path)
+    if state is None:
+        state = {
+            "schemaVersion": SCHEMA_VERSION, "revisionId": revision_id,
+            "contentDigest": publication["contentDigest"], "revisionPath": publication["revisionPath"],
+            "sourceKey": source_key(revision_id), "status": PENDING, "entryId": None, "entryPath": None,
+            "refusal": None, "reason": "not registered yet", "attempts": [],
+        }
+        _set_summary(store, state, sequence, render_summary(json.loads(data), publication), "generated")
+    if summary_text is not None:
+        if state["status"] == REGISTERED:
+            raise DiscussionStoreError(
+                f"{revision_id} is already registered as {state['entryId']}; a registered entry is not replaced"
+            )
+        if _digest(summary_text.encode("utf-8")) == state["summaryDigest"]:
+            raise DiscussionStoreError(
+                f"the summary of {revision_id} is unchanged; edit it before registering again"
+            )
+        _set_summary(store, state, sequence, summary_text, "user")
+        if state["status"] == REFUSED:
+            state.update({"status": PENDING, "reason": "the summary changed after the refusal"})
+    _save_state(path, state)
+    return state
+
+
+def _run_memory_add(okstra_cli: str, store: DiscussionStore, state: dict[str, Any]) -> dict[str, Any]:
+    """결과를 등록·거부·일시 실패 셋으로 나눈다. 거부는 같은 입력에 같은 답이라 다시 부르지 않는다."""
+    if not okstra_cli:
+        return {"outcome": PENDING, "reason": "no okstra CLI path was given (--okstra-cli)"}
+    project_id = state["revisionId"].split(":", 1)[0]
+    command = [
+        okstra_cli, "memory", "add", "--file", str(store.project_root / state["summaryPath"]),
+        "--title", f"Discussion outcome {state['revisionId']}", "--type", "decision",
+        "--source", "discussion", "--source-key", state["sourceKey"], "--project", project_id,
+        "--tag", "discussion", "--yes", "--json",
+    ]
+    try:
+        completed = subprocess.run(command, capture_output=True, text=True, timeout=_TIMEOUT_SECONDS, check=False)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return {"outcome": PENDING, "reason": f"okstra memory add did not run: {exc}"}
+    try:
+        payload = json.loads(completed.stdout)
+    except json.JSONDecodeError:
+        payload = None
+    if isinstance(payload, dict) and payload.get("refused") == "secret":
+        return {"outcome": REFUSED, "secrets": payload.get("secrets") or [], "reason": payload.get("message", "")}
+    entry = payload.get("entry") if isinstance(payload, dict) and payload.get("ok") else None
+    if completed.returncode == 0 and isinstance(entry, dict) and isinstance(entry.get("id"), str):
+        return {"outcome": REGISTERED, "entryId": entry["id"], "entryPath": payload.get("path"),
+                "created": bool(payload.get("created"))}
+    detail = (completed.stderr or completed.stdout).strip().splitlines()
+    return {"outcome": PENDING,
+            "reason": f"okstra memory add exited {completed.returncode}: {detail[-1] if detail else 'no output'}"}
+
+
+def _record_locked(store: DiscussionStore, revision_id: str, summary_digest: str, result: dict[str, Any]) -> dict[str, Any]:
+    _, sequence = parse_revision_id(revision_id)
+    path = _state_path(store, sequence)
+    state = _load_state(path)
+    if state is None:
+        raise DiscussionStoreError(f"the memory state of {revision_id} disappeared during registration")
+    state["attempts"].append({
+        "at": _now_iso(), "summaryDigest": summary_digest, "outcome": result["outcome"],
+        "reason": result.get("reason", ""), "entryId": result.get("entryId"),
+    })
+    # 같은 확정본을 동시에 등록한 다른 호출이 먼저 끝냈으면 그 결과를 지킨다.
+    if state["status"] != REGISTERED and summary_digest == state["summaryDigest"]:
+        if result["outcome"] == REGISTERED:
+            state.update({"status": REGISTERED, "entryId": result["entryId"], "entryPath": result["entryPath"],
+                          "reason": "", "refusal": None})
+        elif result["outcome"] == REFUSED:
+            state.update({"status": REFUSED, "reason": result["reason"], "refusal": {
+                "summaryDigest": summary_digest, "secrets": result["secrets"], "message": result["reason"]}})
+        else:
+            state.update({"status": PENDING, "reason": result["reason"]})
+    _save_state(path, state)
+    return state
+
+
+def register_revision(
+    store: DiscussionStore, revision_id: str, *, okstra_cli: str, summary_text: Optional[str] = None,
+) -> dict[str, Any]:
+    with dir_flock(store.dir, _LOCK_FILENAME):
+        state = _prepare_locked(store, revision_id, summary_text)
+    if state["status"] in (REGISTERED, REFUSED):
+        return view(state)
+    result = _run_memory_add(okstra_cli, store, state)
+    with dir_flock(store.dir, _LOCK_FILENAME):
+        return view(_record_locked(store, revision_id, state["summaryDigest"], result))
+
+
+def _publications(store: DiscussionStore) -> list[dict[str, Any]]:
+    rows, _ = _read_records(store)
+    return _of(rows, "publication")
+
+
+def sync(
+    store: DiscussionStore, *, okstra_cli: str, revision_id: str = "", summary_text: Optional[str] = None,
+) -> list[dict[str, Any]]:
+    """발행된 확정본 가운데 등록되지 않은 것을 같은 출처 키로 다시 등록한다. 거부된 요약은 건너뛴다."""
+    if summary_text is not None and not revision_id:
+        raise DiscussionStoreError("--summary-file needs --revision: a summary belongs to one revision")
+    targets = [row["revisionId"] for row in _publications(store)]
+    if revision_id:
+        if revision_id not in targets:
+            raise DiscussionStoreError(f"no revision {revision_id} is published in this discussion")
+        targets = [revision_id]
+    return [register_revision(store, target, okstra_cli=okstra_cli,
+                              summary_text=summary_text if target == revision_id else None)
+            for target in targets]
+
+
+def view(state: dict[str, Any]) -> dict[str, Any]:
+    out = {key: state[key] for key in ("revisionId", "sourceKey", "status", "entryId", "summaryPath", "reason")}
+    out["attempts"] = len(state["attempts"])
+    if state["status"] == REFUSED:
+        out["secrets"] = state["refusal"]["secrets"]
+        task_key = state["revisionId"].rpartition(_REVISION_SEPARATOR)[0]
+        out["next"] = (f"edit a copy of {state['summaryPath']} without the secret and run `okstra discussion "
+                       f"memory-sync {task_key} --revision {state['revisionId']} --summary-file <edited copy>`")
+    elif state["status"] == PENDING:
+        out["next"] = _SYNC_HINT
+    return out
+
+
+def views(store: DiscussionStore) -> list[dict[str, Any]]:
+    """읽기만 한다. 상태 파일이 없는 발행은 아직 등록을 시도하지 않은 것이다."""
+    rows = []
+    for publication in _publications(store):
+        state = _load_state(_state_path(store, publication["sequence"]))
+        rows.append(view(state) if state is not None else {
+            "revisionId": publication["revisionId"], "sourceKey": source_key(publication["revisionId"]),
+            "status": PENDING, "entryId": None, "summaryPath": None, "reason": "not registered yet",
+            "attempts": 0, "next": _SYNC_HINT,
+        })
+    return rows

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

@@ -0,0 +1,85 @@
+"""관리자 조회용 토론 요약 — 원본을 복제하지 않고 식별자·상태·경로만 읽는다.
+
+토론 원본은 토론 task 아래에 있고, 후속 작업이 쓰는 확정본의 정본은 그 작업의 브리프다.
+여기서는 둘 다 다시 읽기만 하며 어느 프로젝트에도 쓰지 않는다. 읽을 수 없는 것은 `unknown`
+으로 돌려 오래된 값을 현재 상태로 보이지 않게 한다.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from okstra_ctl.json_boundary import JsonBoundaryError
+
+from . import followup
+from .store import DiscussionStore, DiscussionStoreError, has_records, project_draft, read_revision
+
+UNKNOWN = "unknown"
+_FOLLOW_UP_FIELDS = (
+    "followUp", "targetTaskKey", "targetProjectRoot", "briefPath", "state", "reason",
+    "linkedRevision", "pinnedRevision", "latestRevision", "applyRecord", "hasPlan", "planBasis",
+    "amendedPlan", "amendmentRecord",
+)
+
+
+def _questions(draft: dict[str, Any]) -> dict[str, list[dict[str, Any]]]:
+    by_id = {row["recordId"]: row for row in draft["questions"]}
+    return {
+        "forUser": [{key: by_id[qid][key] for key in ("recordId", "author", "text")}
+                    for qid in draft["pendingForUser"]],
+        "forParticipants": [{key: by_id[qid][key] for key in ("recordId", "to", "text")}
+                            for qid in draft["pendingForParticipants"]],
+    }
+
+
+def _revisions(store: DiscussionStore, draft: dict[str, Any]) -> list[dict[str, Any]]:
+    rows = []
+    for publication in draft["revisions"]:
+        row = {key: publication[key] for key in ("revisionId", "sequence", "contentDigest", "revisionPath")}
+        try:
+            _, data = read_revision(store, publication["revisionId"])
+            previous = json.loads(data).get("previousRevision")
+        except (DiscussionStoreError, OSError, ValueError) as exc:
+            rows.append({**row, "state": UNKNOWN, "reason": str(exc)})
+            continue
+        rows.append({
+            **row, "state": "published",
+            "previousRevision": previous["revisionId"] if previous else None,
+            "changeReason": previous["changeReason"] if previous else None,
+        })
+    return rows
+
+
+def _follow_ups(store: DiscussionStore) -> dict[str, Any]:
+    try:
+        view = followup.links(store)
+    except (DiscussionStoreError, OSError, JsonBoundaryError) as exc:
+        return {"state": UNKNOWN, "reason": f"the follow-up links cannot be read: {exc}", "items": [], "unlinked": []}
+    return {
+        "state": "read",
+        "items": [{key: row[key] for key in _FOLLOW_UP_FIELDS if key in row} for row in view["followUps"]],
+        "unlinked": view["unlinkedFollowUps"],
+    }
+
+
+def discussion_overview(store: DiscussionStore) -> dict[str, Any]:
+    source = store.dir.relative_to(store.project_root).as_posix()
+    try:
+        if not has_records(store):
+            return {"state": UNKNOWN, "source": source, "reason": f"{source} holds no discussion record"}
+        draft = project_draft(store)
+    except (DiscussionStoreError, OSError) as exc:
+        return {"state": UNKNOWN, "source": source, "reason": f"the discussion record cannot be read: {exc}"}
+    based_on = draft["basedOn"]
+    return {
+        "state": "completed" if draft["completedRevision"] else "draft",
+        "source": source,
+        "phase": draft["phase"],
+        "draftVersion": draft["recordsDigest"],
+        "completedRevision": draft["completedRevision"],
+        "reopenedFrom": {"revisionId": based_on["revisionId"], "reason": based_on["reason"]} if based_on else None,
+        "pendingQuestions": _questions(draft),
+        "revisions": _revisions(store, draft),
+        "followUps": _follow_ups(store),
+    }
+

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

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": "1.0",
+  "id": "discussion",
+  "roles": [
+    {
+      "mode": "static",
+      "roleId": "analyser",
+      "dutyId": "discussion-worker",
+      "min": 1,
+      "recommended": 3,
+      "max": 5
+    },
+    {
+      "mode": "static",
+      "roleId": "report-writer",
+      "dutyId": "report-writer",
+      "min": 1,
+      "recommended": 1,
+      "max": 1
+    },
+    {
+      "mode": "dynamic",
+      "roleId": "verifier",
+      "dutyId": "reverification-worker",
+      "sourceRoleIds": [
+        "analyser"
+      ],
+      "activation": "per-selected-source"
+    }
+  ]
+}

package/runtime/python/okstra_ctl/phases/discussion/profile.md

@@ -0,0 +1,48 @@
+# Discussion Profile
+
+- Purpose: settle the requirements and implementation direction of a ticket or project together with the user and several agents, preserving disagreements, before any follow-up task plans or implements the work
+{{INCLUDE:_common-contract.md}}
+- Facilitator (the `leader` role):
+  - confirm the discussion subject and the question to settle with the user before dispatching research
+  - keep the discussion record only through `okstra discussion` with this run's manifest as `--run-manifest`: `confirm-subject` for the confirmed subject and question, `ask` for a question to the user, `address` for the user's question to one participant, `answer` for every answer, `decide` for a user decision, and `draft` to read the record every participant gets as its next input. Never write or edit the files under `<task-root>/discussion/` yourself; a resend of the same record is harmless
+  - run `okstra discussion status` on entry and on resume; it names the phase and the one question to put to the user next
+  - relay the questions, contested points and refutation results to the invoking conversation, and put questions to the user one at a time, in the order `status` gives
+  - share every user answer, and every answer to a question the user addressed to one participant, with all participants as input to the next cycle; the draft every instruction carries already holds them
+  - record the user's intent and priorities as user decisions; record claims about the current code or external facts as claims that need evidence. A fact check never settles the user's intent
+  - record new evidence or a new alternative with `add-material`; only a start input, the subject, an answer or a material makes the next research input differ from the last one
+  - the discussion completes only when the user has seen the remaining disagreements and risks, chosen a direction and confirmed completion. Agent consensus, a convergence stop or the end of a worker batch is not completion
+- Research cycle (one per run):
+  - run `okstra discussion cycle-open`. On `dispatch`, materialize one `initial` invocation per analyser with the returned `instructionPath` as `--instruction` and dispatch them as one batch. `await-user` / `await-participant` / `await-recovery` mean nothing is dispatched until that wait ends. `present-options` means the input references equal the last closed cycle's: present the remaining disagreements and options to the user instead of researching again. `prepare-run` means the next cycle needs a continuation run prepared with `--discussion-start <task-key>`
+  - after the batch settles, run `okstra discussion settle`, then group the factual claims for Phase 5.5 convergence; register each question only the user can answer with `ask --author <worker-id>` instead of grouping it
+  - after `okstra convergence finalize`, run `okstra discussion cycle-close`. It records the claims with their original authors and the verifiers' verdicts and ends this verification cycle only; the discussion stays a draft
+- Direct questions:
+  - when the user asks one participant directly, record it with `address`, run `okstra discussion question-prompt`, materialize the batch file it names and dispatch it as a new invocation (no provider session is reused), then run `okstra discussion collect-answer`, which records the participant's whole result as the answer
+- Failures:
+  - when `settle` or `collect-answer` reports a failure, show the user which participant failed and which scope was not verified, then record the user's choice with `okstra discussion recover`: `retry` (a new invocation in this run), `replace` (a continuation run with the new roster; completed results stay recorded with their authors) or `reduce` (continue with the remaining participants). Never replace a participant automatically
+- Completion:
+  - record every settled requirement with `okstra discussion add-requirement` (`--applies-to <follow-up label>` when only one follow-up needs it) and every in-scope and excluded item with `add-scope`; record an explicit `none` when nothing is excluded. These belong to the current draft only. After `reopen`, the draft already holds the reopened revision's requirements and scope, each marked with the revision it was carried from: do not record them again. When the user drops one, record `okstra discussion withdraw --item <N-NNNN|B-NNNN> --reason <the user's reason>`; when the user changes one, withdraw it and add the new one
+  - show the user the draft (`okstra discussion draft`) with the remaining disagreements, the unverified scope and the reduced-roster history; ask the user to choose a direction and to confirm the risks they accept. Remaining disagreements do not block completion; the user's confirmation does
+  - run `okstra discussion confirm-completion` with the `draftVersion` that `status` printed for the draft the user saw, the user's direction and risk confirmation in their words. A refusal names what is missing (subject, requirement, in-scope or excluded entry, a closed research cycle, an unanswered question, a failure without the user's choice) or says the draft changed since that version: show the current draft and ask again. Never confirm on the user's behalf; a resend of the same confirmation returns the published revision
+  - `confirm-completion` also registers the revision in the Memory Book by itself; its `memory` field says `registered`, `pending` or `refused`. A `pending` registration (also listed by `status` under `memoryRegistration` on entry and on resume) is retried with `okstra discussion memory-sync`; the revision stays published either way. A `refused` one names the likely secrets: show them to the user and register again only with the summary the user edited, via `memory-sync --revision <revision-id> --summary-file <path>`. Never edit the files under `<task-root>/discussion/memory/` yourself
+  - the published revision under `<task-root>/discussion/revisions/` is the canonical outcome. Report assembly puts only its id and content digest into the final report's `discussion` block, or the draft version when the user has not confirmed; finalize the run either way. `okstra report-finalize` never confirms completion
+  - to change a completed discussion, prepare a continuation run with `--discussion-start <task-key>` and record `okstra discussion reopen --revision <latest revision id> --reason <why>` before any other record; the next revision carries that reference and reason, and its `itemChanges` lists what it carried, added and withdrawn. Earlier revisions stay readable byte-for-byte with `revision-show`; `record` prints the whole discussion record with every research result in full
+- Follow-ups (only when the user asks, after a revision is published):
+  - write one follow-up task's brief with `okstra discussion follow-up-brief`: it carries the common requirements and those of that follow-up label, recommends `requirements-discovery` and pins the revision. Map a requirement to an end state with `--end-state <N-NNNN>=<EB|PB|EO>` only as the user states it; an observation method the revision does not carry leaves the brief `pending` for the user's confirmation (okstra-brief-gen Step 6.5). Never mark it confirmed for the user
+  - after a re-discussion publishes a newer revision, show `okstra discussion links` and `okstra discussion impact` to the user and record only the user's choice per follow-up with `okstra discussion apply --choice adopt|keep`. A follow-up that already has an implementation-planning plan is routed to the plan amendment path; nothing here edits a plan or source, and no follow-up run is started from this run
+  - a routed follow-up stays `amendment-pending` until the user approves an amended plan in the planning path. When `links` shows `next` naming `okstra discussion complete-amendment`, run it to move that follow-up's brief to the revision; otherwise show the user what `next` says is missing. Never approve a plan for the user
+- Worker research procedure:
+  - research the subject independently and return evidence, assumptions and alternative directions; give each claim its evidence location and say what the evidence could not reach
+  - keep factual claims (what the code or an external source does) apart from questions only the user can answer (intent, scope, priority, acceptable risk)
+  - for each alternative direction, state what it requires, what it excludes and the risk it carries, without ranking it into a decision the user has not made
+- Census aspects:
+  - task subject-framing: What exactly is the subject and the question to settle, and where does the request leave it ambiguous?
+  - task factual-claims: Which claims about the current code or external facts bear on the decision, and what evidence establishes or refutes each?
+  - task alternative-directions: Which alternative directions exist, and what does each require, exclude and risk?
+  - task user-decisions: Which questions can only the user answer, and what does each answer change?
+- Cross-verification mode:
+  - Phase 5.5 convergence runs in **adversarial mode** for factual claims. Verifiers try to refute each claim by re-inspecting the cited evidence. A convergence stop ends one verification cycle; it does not end the discussion.
+  - A participant checking its own claim is not an independent refutation.
+- Non-goals:
+  - **source code edits, detailed implementation plans, builds, or deployments** — the follow-up task starts at `requirements-discovery` and plans the work there
+  - starting a follow-up task's run, or editing its plan or source, inside this run
+  - **writes outside `<PROJECT_ROOT>/.okstra/`**

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

@@ -0,0 +1,73 @@
+"""토론 실행 보고서 — 확정본 참조 블록과 그 검사, 표시 모델.
+
+확정본이 정본이다. 보고서의 `discussion` 블록은 조립이 토론 기록에서 만들고 확정본 id 와
+내용 digest 만 싣는다. 보고서 작성자는 이 블록을 쓰지 않는다.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+from okstra_ctl.report_html.common import evidence_index
+from okstra_ctl.report_html.models import HumanReportView
+
+from .store import (
+    DiscussionStore,
+    DiscussionStoreError,
+    parse_revision_id,
+    read_draft,
+    read_revision,
+    same_task,
+)
+from .validation import revision_errors
+
+REPORT_BLOCK = "discussion"
+
+
+def discussion_report_block(project_root: Path, task_key: str) -> dict[str, str]:
+    """보고서를 조립하는 시점의 토론 상태 — 완료면 확정본 참조, 아니면 초안 버전."""
+    draft = read_draft(DiscussionStore(project_root, task_key))
+    if draft["completedRevision"] is None:
+        return {"outcome": "draft", "draftVersion": draft["recordsDigest"]}
+    latest = draft["revisions"][-1]
+    return {"outcome": "revision", "revisionId": latest["revisionId"], "contentDigest": latest["contentDigest"]}
+
+
+def discussion_report_errors(data: Mapping[str, Any], project_root: Path) -> list[str]:
+    header = data.get("header") or {}
+    if header.get("taskType") != "discussion":
+        return []
+    block = data.get(REPORT_BLOCK)
+    if not isinstance(block, Mapping):
+        return ["discussion: the report has no `discussion` block"]
+    if block.get("outcome") != "revision":
+        return []
+    try:
+        task_key, _ = parse_revision_id(str(block.get("revisionId") or ""))
+        if not same_task(task_key, str(header.get("taskKey") or "")):
+            return [f"discussion: {block['revisionId']} is not a revision of {header.get('taskKey')}"]
+        publication, content = read_revision(DiscussionStore(project_root, task_key), block["revisionId"])
+    except DiscussionStoreError as exc:
+        return [f"discussion: {exc}"]
+    errors = []
+    if block.get("contentDigest") != publication["contentDigest"]:
+        errors.append(
+            f"discussion: the report names digest {block.get('contentDigest')} for {block['revisionId']}, "
+            f"but the published revision is {publication['contentDigest']}"
+        )
+    errors += [f"discussion: {block['revisionId']}: {error}" for error in revision_errors(json.loads(content))]
+    return errors
+
+
+def build_discussion_view(data: dict) -> HumanReportView:
+    return HumanReportView(
+        "discussion",
+        "html/tasks/discussion.template.html",
+        {
+            "humanSummary": data["humanSummary"],
+            "discussion": data.get(REPORT_BLOCK) or {},
+            "evidenceIndex": evidence_index(data, ()),
+        },
+        (),
+    )

package/runtime/python/okstra_ctl/phases/discussion/report_assets/discussion.template.html

@@ -0,0 +1,15 @@
+{% extends "html/base.template.html" %}
+{% from "html/macros/layout.html" import action_list %}
+
+{% block human_content %}
+<section data-report-section="discussion-outcome">
+  <h2>{{ t('tasks.discussion.outcome') }}</h2>
+  <p>{{ humanSummary.outcome | inline_code }}</p>
+  {% if discussion.outcome == 'revision' %}
+  <p data-discussion-revision="{{ discussion.revisionId }}">{{ t('tasks.discussion.revision') }}: <code>{{ discussion.revisionId }}</code> (<code>{{ discussion.contentDigest }}</code>)</p>
+  {% else %}
+  <p data-discussion-draft="{{ discussion.draftVersion }}">{{ t('tasks.discussion.draft') }}</p>
+  {% endif %}
+  {{ action_list(humanSummary.actions) }}
+</section>
+{% endblock %}

package/runtime/python/okstra_ctl/phases/discussion/report_assets/discussion.template.md

@@ -0,0 +1,6 @@
+{% import "md/macros/sections.md" as s with context -%}
+{{ s.section("discussion", "Discussion Revision") }}
+{#
+  The block references the canonical revision by id and content digest only;
+  `okstra discussion revision-show` prints the revision itself.
+-#}