okstra 0.214.1 → 0.216.0

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

@@ -0,0 +1,512 @@
+"""`okstra discussion` — 진행자가 토론 기록을 쓰고 읽는 유일한 명령."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from okstra_project import (
+    ResolverError,
+    StateError,
+    resolve_project_root,
+    resolve_task_identity,
+)
+
+from . import followup, memory, workflow
+from .store import (
+    COMMON,
+    SCOPE_KINDS,
+    USER,
+    DiscussionStore,
+    DiscussionStoreError,
+    append_record,
+    confirm_completion,
+    read_draft,
+    read_revision,
+    render_draft_text,
+    render_full_record,
+    resolve_source_run,
+)
+
+_CLI_EPILOG = r"""Usage:
+  okstra discussion confirm-subject <task-key> --subject "<what>" --question "<to settle>" --run-manifest <path>
+  okstra discussion ask <task-key> --author <leader|worker-id> --text "<question for the user>" --run-manifest <path>
+  okstra discussion address <task-key> --to <worker-id> --text "<the user's question>" --run-manifest <path>
+  okstra discussion answer <task-key> --question <Q-NNNN> --author <user|worker-id> --text "<answer>" --run-manifest <path>
+  okstra discussion decide <task-key> --text "<the user's decision>" [--question <Q-NNNN>] --run-manifest <path>
+  okstra discussion add-material <task-key> --kind <evidence|alternative> --author <user|leader|worker-id> --text "<what>" --run-manifest <path>
+  okstra discussion draft <task-key>
+  okstra discussion status <task-key>
+  okstra discussion cycle-open <task-key> --run-manifest <path>
+  okstra discussion settle <task-key> --run-manifest <path>
+  okstra discussion recover <task-key> --failure <X-NNNN> --choice <retry|replace|reduce> --run-manifest <path>
+  okstra discussion cycle-close <task-key> --run-manifest <path>
+  okstra discussion question-prompt <task-key> --question <Q-NNNN> --run-manifest <path>
+  okstra discussion collect-answer <task-key> --question <Q-NNNN> --run-manifest <path>
+  okstra discussion add-requirement <task-key> --text "<requirement>" [--applies-to <common|follow-up label>] --author <user|leader|worker-id> --run-manifest <path>
+  okstra discussion add-scope <task-key> --kind <in-scope|excluded> --text "<what>" --author <user|leader|worker-id> --run-manifest <path>
+  okstra discussion withdraw <task-key> --item <N-NNNN|B-NNNN> --reason "<why the user drops it>" --run-manifest <path>
+  okstra discussion confirm-completion <task-key> --draft-version <sha256:...> --direction "<the user's chosen direction>" --risk "<the risks the user accepts>" --run-manifest <path>
+  okstra discussion reopen <task-key> --revision <task-key/revision-NNN> --reason "<why it changes>" --run-manifest <path>
+  okstra discussion revisions <task-key>
+  okstra discussion revision-show <task-key> --revision <task-key/revision-NNN>
+  okstra discussion record <task-key>
+  okstra discussion memory-sync <task-key> [--revision <task-key/revision-NNN> [--summary-file <path>]]
+  okstra discussion follow-up-brief <task-key> --revision <task-key/revision-NNN> --follow-up <label> --target-task <task-key> [--target-project-root <dir>] [--end-state <N-NNNN>=<EB|PB|EO>[:<how to observe>]]... [--replace]
+  okstra discussion links <task-key>
+  okstra discussion impact <task-key> --from <revision-id> --to <revision-id> [--follow-up <label>]
+  okstra discussion apply <task-key> --revision <latest revision-id> --target-task <task-key> --choice <adopt|keep> [--end-state ...]... [--replace]
+  okstra discussion complete-amendment <task-key> --revision <revision-id> --target-task <task-key> [--end-state ...]... [--replace]
+
+Records go to <task-root>/discussion/records.jsonl under a directory lock, and
+the draft read model is rebuilt after every record. --run-manifest names the
+discussion run the record comes from; a manifest of another task, or of another
+task type, is refused. Authors must be `leader` or a worker of that run; a
+question asked with `ask` goes to the user, a question asked with `address`
+comes from the user and goes to the named worker, and only its addressee may
+answer it. Sending the same record again returns the stored record
+(`created: false`) instead of adding a second one.
+
+`draft` prints the fixed-text read model every participant reads: the confirmed
+subject and question, start inputs, user decisions, questions waiting for the
+user or for a participant, and every answered question with its answers.
+
+`status` prints the phase (framing, ready-for-research, researching,
+awaiting-recovery, awaiting-new-run, awaiting-user, awaiting-participant,
+awaiting-choice, completed), the draft version, the published revisions, the
+one question to put to the user next, unrecovered failures and the remaining
+disagreements.
+
+One research and refutation cycle runs per discussion run. `cycle-open` either
+writes the research instruction every analyser receives (action `dispatch`) or
+says why no research is dispatched: `await-user`, `await-participant`,
+`await-recovery`, `present-options` (the input references — start inputs,
+subject, answers, materials — equal the last closed cycle's), `prepare-run` (a
+continuation run with `--discussion-start <task-key>` holds the next cycle), or
+`completed` (the user completed the discussion). `settle` records each analyser's completed result and each failure
+the dispatcher left after its retry loop; `recover` records the user's choice
+for one failure. `cycle-close` imports the run's finalized convergence state as
+claims with their authors and verdicts and ends that verification cycle; it
+never completes the discussion. `question-prompt` writes the instruction and the
+`agent-prompt materialize --batch` file for one direct question, and
+`collect-answer` records the addressee's whole result file as the answer.
+
+Completion belongs to the user. `add-requirement` and `add-scope` record the
+requirements (common, or for one follow-up) and the in-scope and excluded
+items of the current draft; adding an item the draft already holds returns it.
+After `reopen`, the draft starts with the reopened revision's requirements and
+scope, each under its original record id and marked with the revision it was
+carried from. `withdraw` removes one carried or added item with the user's
+reason; replacing an item is `withdraw` followed by `add-requirement` or
+`add-scope`. `confirm-completion` binds the user's direction
+choice and risk confirmation to the draft version `status` and `draft` print;
+it is refused when that version is stale, or while the subject, a requirement,
+an in-scope or excluded entry, a closed research cycle, a user or participant
+answer or a failure choice is missing. It then publishes one immutable
+revision, <task-root>/discussion/revisions/revision-NNN.json, whose id is the
+task key and the completion sequence; resending the same confirmation returns
+the published revision. Remaining disagreements, unverified scope and the
+reduced roster are carried, not blocking. A completed discussion takes no other
+record until `reopen` names the latest revision and the reason for change; the
+next revision then carries that reference and reason, lists under
+`itemChanges` what it carried, added and withdrawn, and earlier revisions
+stay byte-for-byte readable with `revision-show`. `revisions` lists the
+published revisions, `record` prints the draft read model followed by every
+research result in full. Finalizing a run never confirms completion.
+
+Every published revision is registered in the Memory Book after publication,
+without a prompt: `okstra memory add --source-key discussion:<revision-id>`
+stores a summary of its decisions, disagreements, risks and unverified scope
+with the revision id, content digest, project and task — never the discussion
+record itself. The summary and the registration state live in
+<task-root>/discussion/memory/. A failed registration never undoes the
+revision: it stays `pending`, `status` lists it under memoryRegistration, and
+`memory-sync` retries it with the same source key; registering the same
+revision again returns its existing entry. A summary the Memory Book refuses as
+a likely secret is `refused` and is not retried until --summary-file supplies a
+changed summary for that --revision.
+
+Follow-ups run outside a discussion run, at the user's request. `follow-up-brief`
+writes the brief of one follow-up task from one revision: the common
+requirements and those that apply to --follow-up, the confirmed subject,
+direction, scope, exclusions, disagreements and unverified scope, each naming
+its record in the revision. --end-state maps a requirement to an Expected
+Behavior, Preserved Behavior or Expected Outcome item; an observation method the
+revision does not carry is new meaning, so the brief stays
+`reporter-confirmations: pending` with an `intent-check:` row until the user
+confirms it (okstra-brief-gen Step 6.5). The brief lands at
+<target-project-root>/.okstra/briefs/<task-group>/<task-id>-<label>.md, passes
+validators/validate-brief.py, recommends `requirements-discovery`, and pins the
+discussion, the revision id, its content digest and the follow-up's requirement
+ids in its frontmatter; prepare copies that pin into the run inputs as
+`discussionRevisionRef`. The brief is the target task's own record of the
+revision it uses; <task-root>/discussion/links.jsonl only remembers where each
+target is. The brief is written first and the link after it, so resending an
+interrupted command records the link once. A brief this command did not write
+last is not replaced without --replace.
+
+`links` re-reads every linked target: `current`, `needs-impact-review` (a newer
+revision exists and the user has not chosen), `kept`, `amendment-pending`, or
+`unknown` when the target cannot be read; an `amendment-pending` target names the
+approved amended plan, or what is still missing. `impact` prints what changed between
+two revisions, for one follow-up when --follow-up is given. `apply` records the
+user's choice for one target and the latest revision: `keep` changes nothing,
+`adopt` rewrites the brief of a target without an implementation-planning plan,
+and routes a target with a plan to the plan amendment path without touching its
+plan, brief or source. Resending the same choice returns the stored record; a
+different choice for the same target and revision is refused.
+`complete-amendment` finishes a routed adoption once the target has an
+implementation-planning report newer than the one it had when the adoption was
+routed and the user approved it (`frontmatter.approved: true`): it rewrites the
+brief to pin the revision under the same --replace rule and records the plan
+report it relied on. Without that report it is refused and names what is
+missing; it never edits or approves a plan, and a resend returns the record.
+
+Output: JSON { ok, created, record, pendingForUser, pendingForParticipants } for
+the record commands, JSON { ok, ... } for the cycle, status, revisions,
+memory-sync and follow-up commands, a `memory` field with the registration
+state on confirm-completion, plain text for `draft` and `record`, and the revision file's own
+bytes for `revision-show`. Exit 1 on a refusal, 2 when PROJECT_ROOT or the
+task cannot be resolved.
+"""
+
+
+def _add_common(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("task_key", metavar="task-key", help="project-id:task-group:task-id")
+    parser.add_argument("--project-root", "--project", default="",
+                        help="use this directory as PROJECT_ROOT")
+    parser.add_argument("--cwd", default=".", help="resolve PROJECT_ROOT starting from here")
+
+
+def _add_run(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--run-manifest", required=True,
+                        help="the discussion run manifest the record comes from")
+
+
+def _add_target(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--target-task", required=True, help="the follow-up task key")
+    parser.add_argument("--end-state", action="append", default=[],
+                        help="<N-NNNN>=<EB|PB|EO>[:<how to observe it>]; repeat per requirement")
+    parser.add_argument("--replace", action="store_true",
+                        help="replace a brief this command did not write last")
+
+
+def _follow_up(store: DiscussionStore, args: argparse.Namespace) -> dict:
+    if args.command == "links":
+        return followup.links(store)
+    if args.command == "impact":
+        return followup.impact(store, from_revision=args.from_revision, to_revision=args.to_revision,
+                               label=args.follow_up)
+    end_states = [followup.parse_end_state(value) for value in args.end_state]
+    if args.command == "complete-amendment":
+        return followup.complete_amendment(store, revision_id=args.revision, target_key=args.target_task,
+                                           end_states=end_states, replace=args.replace)
+    if args.command == "apply":
+        return followup.apply_revision(store, revision_id=args.revision, target_key=args.target_task,
+                                       choice=args.choice, end_states=end_states, replace=args.replace)
+    target_root = Path(args.target_project_root) if args.target_project_root else store.project_root
+    return followup.create_follow_up(
+        store, revision_id=args.revision, label=args.follow_up,
+        target=followup.target_of(args.target_task, target_root), end_states=end_states, replace=args.replace,
+    )
+
+
+_FOLLOW_UP_COMMANDS = frozenset({"follow-up-brief", "links", "impact", "apply", "complete-amendment"})
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="okstra discussion",
+        description="Record and read a discussion task's questions, answers and decisions, drive its research cycles and publish the user's completed revisions.",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--okstra-cli", default="", help=argparse.SUPPRESS)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    subject = sub.add_parser("confirm-subject", help="record the subject and question the user confirmed")
+    _add_common(subject)
+    subject.add_argument("--subject", required=True)
+    subject.add_argument("--question", required=True)
+    _add_run(subject)
+
+    ask = sub.add_parser("ask", help="register a question for the user")
+    _add_common(ask)
+    ask.add_argument("--author", required=True, help="`leader` or a worker id of the run")
+    ask.add_argument("--text", required=True)
+    _add_run(ask)
+
+    address = sub.add_parser("address", help="register the user's question to one participant")
+    _add_common(address)
+    address.add_argument("--to", required=True, help="the worker id the user addresses")
+    address.add_argument("--text", required=True)
+    _add_run(address)
+
+    answer = sub.add_parser("answer", help="record the answer to a question")
+    _add_common(answer)
+    answer.add_argument("--question", required=True, help="the question id (Q-NNNN)")
+    answer.add_argument("--author", required=True, help="`user` or the addressed worker id")
+    answer.add_argument("--text", required=True)
+    _add_run(answer)
+
+    decide = sub.add_parser("decide", help="record a user decision")
+    _add_common(decide)
+    decide.add_argument("--text", required=True)
+    decide.add_argument("--question", default="", help="the question the decision settles")
+    _add_run(decide)
+
+    material = sub.add_parser("add-material", help="record new evidence or a new alternative")
+    _add_common(material)
+    material.add_argument("--kind", required=True, choices=("evidence", "alternative"))
+    material.add_argument("--author", required=True, help="`user`, `leader` or a worker id of the run")
+    material.add_argument("--text", required=True)
+    _add_run(material)
+
+    draft = sub.add_parser("draft", help="print the draft read model as fixed text")
+    _add_common(draft)
+
+    state = sub.add_parser("status", help="print the phase and the next question for the user")
+    _add_common(state)
+
+    for name, help_text in (
+        ("cycle-open", "open this run's research cycle or say why none is dispatched"),
+        ("settle", "record the research results and failures of this run's cycle"),
+        ("cycle-close", "end this run's verification cycle from its convergence final state"),
+    ):
+        command = sub.add_parser(name, help=help_text)
+        _add_common(command)
+        _add_run(command)
+
+    recover = sub.add_parser("recover", help="record the user's choice for one failure")
+    _add_common(recover)
+    recover.add_argument("--failure", required=True, help="the failure id (X-NNNN)")
+    recover.add_argument("--choice", required=True, choices=workflow.CHOICES)
+    _add_run(recover)
+
+    requirement = sub.add_parser("add-requirement", help="record a requirement of the current draft")
+    _add_common(requirement)
+    requirement.add_argument("--text", required=True)
+    requirement.add_argument("--applies-to", default=COMMON,
+                             help="`common`, or the follow-up the requirement belongs to")
+    requirement.add_argument("--author", required=True, help="`user`, `leader` or a worker id of the run")
+    _add_run(requirement)
+
+    scope = sub.add_parser("add-scope", help="record an in-scope or excluded item of the current draft")
+    _add_common(scope)
+    scope.add_argument("--kind", required=True, choices=SCOPE_KINDS)
+    scope.add_argument("--text", required=True)
+    scope.add_argument("--author", required=True, help="`user`, `leader` or a worker id of the run")
+    _add_run(scope)
+
+    withdraw = sub.add_parser("withdraw", help="withdraw one requirement or scope item from the current draft")
+    _add_common(withdraw)
+    withdraw.add_argument("--item", required=True, help="the requirement or scope record id (N-NNNN or B-NNNN)")
+    withdraw.add_argument("--reason", required=True, help="why the user withdraws it")
+    _add_run(withdraw)
+
+    confirm = sub.add_parser("confirm-completion",
+                             help="record the user's completion confirmation and publish a revision")
+    _add_common(confirm)
+    confirm.add_argument("--draft-version", required=True,
+                         help="the draft version the user confirmed (from `status` or `draft`)")
+    confirm.add_argument("--direction", required=True, help="the direction the user chose")
+    confirm.add_argument("--risk", required=True,
+                         help="the remaining disagreements and risks the user confirmed")
+    _add_run(confirm)
+
+    reopen = sub.add_parser("reopen", help="open a new draft on top of the latest revision")
+    _add_common(reopen)
+    reopen.add_argument("--revision", required=True, help="the latest revision id")
+    reopen.add_argument("--reason", required=True, help="why the outcome changes")
+    _add_run(reopen)
+
+    revisions = sub.add_parser("revisions", help="list the published revisions")
+    _add_common(revisions)
+
+    show = sub.add_parser("revision-show", help="print one published revision byte-for-byte")
+    _add_common(show)
+    show.add_argument("--revision", required=True, help="the revision id (<task-key>/revision-NNN)")
+
+    record = sub.add_parser("record", help="print the whole discussion record as fixed text")
+    _add_common(record)
+
+    sync = sub.add_parser("memory-sync", help="register published revisions the Memory Book does not hold yet")
+    _add_common(sync)
+    sync.add_argument("--revision", default="", help="only this revision")
+    sync.add_argument("--summary-file", default="",
+                      help="a changed summary for --revision, after the Memory Book refused the last one")
+
+    brief = sub.add_parser("follow-up-brief", help="write one follow-up task's brief from a revision")
+    _add_common(brief)
+    brief.add_argument("--revision", required=True, help="the revision id the follow-up uses")
+    brief.add_argument("--follow-up", required=True, help="the follow-up label the requirements apply to")
+    _add_target(brief)
+    brief.add_argument("--target-project-root", default="",
+                       help="the follow-up's project root (default: this discussion's project)")
+
+    links = sub.add_parser("links", help="list the linked follow-ups and their impact-review state")
+    _add_common(links)
+
+    changes = sub.add_parser("impact", help="print what changed between two revisions")
+    _add_common(changes)
+    changes.add_argument("--from", dest="from_revision", required=True, help="the earlier revision id")
+    changes.add_argument("--to", dest="to_revision", required=True, help="the later revision id")
+    changes.add_argument("--follow-up", default="", help="only the requirements of this follow-up")
+
+    adopt = sub.add_parser("apply", help="record the user's choice to adopt or keep the latest revision")
+    _add_common(adopt)
+    adopt.add_argument("--revision", required=True, help="the latest revision id")
+    _add_target(adopt)
+    adopt.add_argument("--choice", required=True, choices=followup.CHOICES)
+
+    amended = sub.add_parser("complete-amendment",
+                             help="move a follow-up routed to plan amendment to the revision after its amended plan is approved")
+    _add_common(amended)
+    amended.add_argument("--revision", required=True, help="the revision the routed adoption named")
+    _add_target(amended)
+
+    for name, help_text in (
+        ("question-prompt", "write the dispatch input of one direct question"),
+        ("collect-answer", "record the addressee's answer to one direct question"),
+    ):
+        command = sub.add_parser(name, help=help_text)
+        _add_common(command)
+        command.add_argument("--question", required=True, help="the question id (Q-NNNN)")
+        _add_run(command)
+    return parser
+
+
+def _workflow(store: DiscussionStore, args: argparse.Namespace) -> dict:
+    run = workflow.load_run(store, args.run_manifest)
+    if args.command == "cycle-open":
+        return workflow.open_cycle(store, run)
+    if args.command == "settle":
+        return workflow.settle_cycle(store, run)
+    if args.command == "cycle-close":
+        return workflow.close_cycle(store, run)
+    if args.command == "recover":
+        return workflow.choose_recovery(store, run, args.failure, args.choice)
+    if args.command == "question-prompt":
+        return workflow.question_dispatch(store, run, args.question)
+    return workflow.collect_answer(store, run, args.question)
+
+
+_WORKFLOW_COMMANDS = frozenset({
+    "cycle-open", "settle", "cycle-close", "recover", "question-prompt", "collect-answer",
+})
+
+
+def _write(store: DiscussionStore, args: argparse.Namespace) -> tuple[dict, bool]:
+    source_run = resolve_source_run(store, args.run_manifest)
+    if args.command == "confirm-subject":
+        return append_record(store, "subject", {"subject": args.subject, "question": args.question},
+                             author=USER, source_run=source_run)
+    if args.command == "ask":
+        return append_record(store, "question", {"to": USER, "text": args.text},
+                             author=args.author, source_run=source_run)
+    if args.command == "address":
+        return append_record(store, "question", {"to": args.to, "text": args.text},
+                             author=USER, source_run=source_run)
+    if args.command == "answer":
+        return append_record(store, "answer", {"questionId": args.question, "text": args.text},
+                             author=args.author, source_run=source_run)
+    if args.command == "add-material":
+        return append_record(store, "material", {"materialKind": args.kind, "text": args.text},
+                             author=args.author, source_run=source_run)
+    if args.command == "add-requirement":
+        return append_record(store, "requirement", {"appliesTo": args.applies_to, "text": args.text},
+                             author=args.author, source_run=source_run)
+    if args.command == "add-scope":
+        return append_record(store, "scope", {"scopeKind": args.kind, "text": args.text},
+                             author=args.author, source_run=source_run)
+    if args.command == "withdraw":
+        return append_record(store, "withdrawal", {"itemId": args.item, "reason": args.reason},
+                             author=USER, source_run=source_run)
+    if args.command == "confirm-completion":
+        return confirm_completion(store, draft_version=args.draft_version, direction=args.direction,
+                                  risk_acknowledgement=args.risk, source_run=source_run)
+    if args.command == "reopen":
+        return append_record(store, "reopen", {"revisionId": args.revision, "reason": args.reason},
+                             author=USER, source_run=source_run)
+    return append_record(store, "decision", {"questionId": args.question, "text": args.text},
+                         author=USER, source_run=source_run)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    def emit(payload: dict) -> None:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+    try:
+        project_root = Path(resolve_project_root(explicit_root=args.project_root, cwd=args.cwd))
+        identity = resolve_task_identity(project_root, args.task_key)
+    except (ResolverError, StateError) as exc:
+        emit({"ok": False, "stage": "resolve", "reason": str(exc)})
+        return 2
+    store = DiscussionStore(project_root, identity["taskKey"])
+    try:
+        if args.command == "draft":
+            print(render_draft_text(read_draft(store)), end="")
+            return 0
+        if args.command == "status":
+            emit({"ok": True, **workflow.status(read_draft(store)), "memoryRegistration": memory.views(store)})
+            return 0
+        if args.command == "memory-sync":
+            summary = _read_summary(args.summary_file) if args.summary_file else None
+            emit({"ok": True, "memory": memory.sync(store, okstra_cli=args.okstra_cli,
+                                                    revision_id=args.revision, summary_text=summary)})
+            return 0
+        if args.command == "record":
+            print(render_full_record(store), end="")
+            return 0
+        if args.command == "revisions":
+            emit({"ok": True, "revisions": read_draft(store)["revisions"]})
+            return 0
+        if args.command == "revision-show":
+            _, data = read_revision(store, args.revision)
+            sys.stdout.write(data.decode("utf-8"))
+            return 0
+        if args.command in _FOLLOW_UP_COMMANDS:
+            emit({"ok": True, **_follow_up(store, args)})
+            return 0
+        if args.command in _WORKFLOW_COMMANDS:
+            emit({"ok": True, **_workflow(store, args)})
+            return 0
+        record, created = _write(store, args)
+        draft = read_draft(store)
+    except DiscussionStoreError as exc:
+        emit({"ok": False, "stage": args.command, "reason": str(exc)})
+        return 1
+    payload = {
+        "ok": True,
+        "created": created,
+        "record": record,
+        "pendingForUser": draft["pendingForUser"],
+        "pendingForParticipants": draft["pendingForParticipants"],
+    }
+    if args.command == "confirm-completion":
+        payload["memory"] = _register(store, record["revisionId"], args.okstra_cli)
+    emit(payload)
+    return 0
+
+
+def _read_summary(path: str) -> str:
+    try:
+        return Path(path).read_text(encoding="utf-8")
+    except OSError as exc:
+        raise DiscussionStoreError(f"--summary-file {path} cannot be read: {exc}") from exc
+
+
+def _register(store: DiscussionStore, revision_id: str, okstra_cli: str) -> dict:
+    """확정본은 이미 발행됐다 — 등록 실패는 발행을 되돌리지 않고 `pending` 으로 남아 `memory-sync` 가 다시 부른다."""
+    try:
+        return memory.register_revision(store, revision_id, okstra_cli=okstra_cli)
+    except (DiscussionStoreError, OSError) as exc:
+        return {"revisionId": revision_id, "sourceKey": memory.source_key(revision_id), "status": memory.PENDING,
+                "reason": f"registration did not start: {exc}", "next": "okstra discussion memory-sync <task-key>"}
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,116 @@
+"""토론 시작 입력을 분류·검증하고, 그 입력으로 단계 소유 입력 문서를 만든다."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from okstra_ctl.prepare_error import PrepareError
+
+from .store import (
+    USER,
+    DiscussionStore,
+    DiscussionStoreError,
+    SourceRun,
+    append_record,
+    completed_revision,
+    has_records,
+    read_draft,
+    render_draft_text,
+    same_task,
+)
+
+_URL = re.compile(r"^https?://\S+$")
+_TASK_KEY = re.compile(r"^[^:\s]+:[^:\s]+:[^:\s]+$")
+
+
+def _task_key(inp) -> str:
+    return f"{inp.project_id}:{inp.task_group}:{inp.task_id}"
+
+
+def classify_start_input(text: str, project_root: Path, task_key: str) -> tuple[str, str]:
+    """호출자에게 종류를 묻지 않고 값의 모양으로 정한다 — URL·프로젝트 안 파일은 link,
+    task key 모양은 이 task 의 토론, 나머지는 description."""
+    value = text.strip()
+    if not value:
+        raise PrepareError(
+            "--discussion-start is empty — give a ticket or project link, a short "
+            "description, or this task's key to continue its discussion"
+        )
+    if _URL.match(value):
+        return "link", value
+    if _TASK_KEY.match(value):
+        if not same_task(value, task_key):
+            raise PrepareError(
+                f"--discussion-start names the discussion of {value}, not of {task_key}; "
+                "a discussion continues in its own task — start this task from a link "
+                "or a description instead"
+            )
+        if not has_records(DiscussionStore(project_root, task_key)):
+            raise PrepareError(
+                f"{task_key} has no discussion record to continue yet — start it from "
+                "a link or a description"
+            )
+        return "discussion", task_key
+    candidate = project_root / value
+    if "\n" not in value and candidate.is_file():
+        try:
+            return "link", candidate.resolve().relative_to(project_root.resolve()).as_posix()
+        except ValueError:
+            # expected-miss: 프로젝트 밖 파일은 링크가 아니라 설명으로 기록한다.
+            return "description", value
+    return "description", value
+
+
+def validate_discussion_start(project_root: Path, inp) -> None:
+    """prepare 의 어떤 쓰기보다 먼저 돈다 — 입력 오류가 부분 run 을 남기지 않게."""
+    if inp.task_type != "discussion":
+        if inp.discussion_start:
+            raise PrepareError(
+                "--discussion-start is only meaningful with --task-type discussion; "
+                f"got {inp.task_type}"
+            )
+        return
+    if str(inp.brief_path).strip() not in ("", "."):
+        raise PrepareError(
+            "--task-brief is not accepted for --task-type discussion — pass "
+            "--discussion-start <link | short description | this task's key>; "
+            "prepare writes the discussion input document itself"
+        )
+    task_key = _task_key(inp)
+    kind, _ = classify_start_input(inp.discussion_start, project_root, task_key)
+    try:
+        completed = completed_revision(DiscussionStore(project_root, task_key))
+    except DiscussionStoreError as exc:
+        raise PrepareError(str(exc)) from exc
+    if completed is not None and kind != "discussion":
+        raise PrepareError(
+            f"{task_key} is completed as {completed}; continue it with --discussion-start "
+            f"{task_key} and reopen it (`okstra discussion reopen`) to discuss a change"
+        )
+
+
+def materialize_discussion_input(project_root: Path, inp, ctx: dict) -> None:
+    task_key = _task_key(inp)
+    kind, text = classify_start_input(inp.discussion_start, project_root, task_key)
+    store = DiscussionStore(project_root, task_key)
+    try:
+        if kind != "discussion":
+            append_record(
+                store, "start", {"startKind": kind, "text": text},
+                author=USER,
+                source_run=SourceRun(
+                    manifest=str(ctx["RUN_MANIFEST_RELATIVE_PATH"]),
+                    participants=frozenset(),
+                ),
+            )
+        draft = read_draft(store)
+    except DiscussionStoreError as exc:
+        raise PrepareError(str(exc)) from exc
+    store.input_path.write_text(
+        "# Discussion input\n\n"
+        f"- Start input of this run: [{kind}] {text}\n"
+        f"- Run: `{ctx['RUN_MANIFEST_RELATIVE_PATH']}`\n\n"
+        + render_draft_text(draft),
+        encoding="utf-8",
+    )
+    inp.brief_path = store.input_path