okstra 0.214.1 → 0.216.0

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

@@ -0,0 +1,876 @@
+"""후속 작업 — 확정본으로 후속 브리프를 만들고, 연결된 작업의 영향 검토와 선택 적용을 기록한다.
+
+후속 작업이 어느 확정본을 쓰는지의 정본은 그 작업의 브리프 frontmatter 다. prepare 가 그 값을
+run 입력 기록(`discussionRevisionRef`)으로 옮긴다. 토론 쪽 `links.jsonl` 은 대상의 위치와 적용
+기록만 갖고, 상태는 조회할 때마다 대상에서 다시 읽는다 — 두 프로젝트를 한 번의 쓰기로 묶을 수
+없으므로 대상 쓰기를 먼저 하고 연결 기록을 뒤에 남긴다.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+from typing import Any, Callable, Iterator, Mapping, Optional
+
+from okstra_ctl.brief_frontmatter import read_brief_frontmatter
+from okstra_ctl.ids import slugify_task_segment
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
+from okstra_ctl.manager_split import _fence, _load_brief_validator, _validate_rendered, brief_file_title
+from okstra_ctl.manager_store import ManagerError
+from okstra_ctl.paths import RunRef
+from okstra_ctl.plan_approval import plan_is_approved
+from okstra_ctl.plan_run_root import implementation_planning_report_seq, list_implementation_planning_reports
+from okstra_ctl.run_context import dir_flock
+
+from .store import (
+    _LOCK_FILENAME,
+    COMMON,
+    USER,
+    DiscussionStore,
+    DiscussionStoreError,
+    _complete_lines,
+    _now_iso,
+    _split_task_key,
+    drop_incomplete_line,
+    project_draft,
+    read_draft,
+    read_revision,
+    same_task,
+)
+
+SCHEMA_VERSION = "1.0"
+GENERATOR = "okstra-discussion"
+SOURCE_TYPE = "discussion"
+RECOMMENDED_PHASE = "requirements-discovery"
+END_STATE_SECTIONS = (("EB", "Expected Behavior"), ("PB", "Preserved Behavior"), ("EO", "Expected Outcome"))
+CHOICES = ("adopt", "keep")
+NONE = "_(none)_"
+
+FM_TASK = "discussion-task"
+FM_REVISION = "discussion-revision"
+FM_DIGEST = "discussion-content-digest"
+FM_FOLLOW_UP = "discussion-follow-up"
+FM_REQUIREMENTS = "discussion-requirements"
+
+_PREFIX = {"link": "L", "apply": "Y", "amendment": "Z"}
+_IDENTITY_FIELDS = {
+    "link": ("targetTaskKey", "revisionId", "followUp", "briefSha256"),
+    "apply": ("targetTaskKey", "revisionId", "choice"),
+    "amendment": ("targetTaskKey", "revisionId"),
+}
+ROUTED = "routed-to-plan-amendment"
+
+
+class FollowUpError(DiscussionStoreError):
+    pass
+
+
+@dataclass(frozen=True)
+class EndState:
+    requirement_id: str
+    kind: str
+    verify: str
+
+
+@dataclass(frozen=True)
+class Target:
+    task_key: str
+    project_root: Path
+
+    @property
+    def parts(self) -> tuple[str, str, str]:
+        return _split_task_key(self.task_key)
+
+    def brief_path(self, label: str) -> Path:
+        _, group, task_id = self.parts
+        title = brief_file_title(label)
+        stem = slugify_task_segment(task_id) + (f"-{title}" if title else "")
+        return self.project_root / ".okstra" / "briefs" / slugify_task_segment(group) / f"{stem}.md"
+
+
+def parse_end_state(value: str) -> EndState:
+    head, separator, rest = value.partition("=")
+    kind, _, verify = rest.partition(":")
+    kind = kind.strip().upper()
+    if not separator or not head.strip() or kind not in {code for code, _ in END_STATE_SECTIONS}:
+        raise FollowUpError(f"--end-state {value!r} must be <N-NNNN>=<EB|PB|EO>[:<observation method>]")
+    return EndState(head.strip(), kind, " ".join(verify.split()))
+
+
+def target_of(task_key: str, project_root: Path) -> Target:
+    _split_task_key(task_key)
+    return Target(task_key, Path(project_root).resolve())
+
+
+def _norm(text: Any) -> str:
+    return " ".join(str(text or "").split())
+
+
+def _sha(data: bytes) -> str:
+    return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def _validator() -> ModuleType:
+    try:
+        return _load_brief_validator()
+    except ManagerError as exc:
+        raise FollowUpError(str(exc)) from exc
+
+
+def follow_up_labels(revision: Mapping[str, Any]) -> list[str]:
+    return sorted({row["appliesTo"] for row in revision["requirements"]} - {COMMON})
+
+
+def _own_requirements(revision: Mapping[str, Any], label: str) -> list[dict[str, Any]]:
+    return [row for row in revision["requirements"] if row["appliesTo"] in (COMMON, label)]
+
+
+def brief_revision_ref(path: Path) -> Optional[dict[str, Any]]:
+    """브리프가 고정한 확정본 — 없으면 토론의 후속 브리프가 아니다."""
+    frontmatter = read_brief_frontmatter(Path(path))
+    if not frontmatter.get(FM_REVISION):
+        return None
+    return {
+        "discussionTaskKey": frontmatter.get(FM_TASK, ""),
+        "revisionId": frontmatter[FM_REVISION],
+        "contentDigest": frontmatter.get(FM_DIGEST, ""),
+        "followUp": frontmatter.get(FM_FOLLOW_UP, ""),
+        "requirementIds": frontmatter.get(FM_REQUIREMENTS, "").split(),
+    }
+
+
+# ---- 브리프 ---------------------------------------------------------------
+
+
+def _end_state_items(
+    revision: Mapping[str, Any], own: list[dict[str, Any]], mapping: Mapping[str, EndState], verify_re: Any,
+) -> tuple[dict[str, list[str]], list[dict[str, Any]], list[dict[str, Any]]]:
+    """확정본 요구사항 → 끝 상태 항목. 관찰 방법을 이 변환이 더하면 새 의미라 사용자 확인 대상이다."""
+    items: dict[str, list[str]] = {code: [] for code, _ in END_STATE_SECTIONS}
+    rows: list[dict[str, Any]] = []
+    unmapped: list[dict[str, Any]] = []
+    for requirement in own:
+        end_state = mapping.get(requirement["recordId"])
+        if end_state is None:
+            unmapped.append(requirement)
+            continue
+        text = _norm(requirement["text"])
+        carries = bool(verify_re.search(text))
+        if carries and end_state.verify:
+            raise FollowUpError(
+                f"{requirement['recordId']} already carries an observation method in {revision['revisionId']}; "
+                f"pass --end-state {requirement['recordId']}={end_state.kind} without one"
+            )
+        if not carries and not end_state.verify:
+            raise FollowUpError(
+                f"{requirement['recordId']} has no observation method in {revision['revisionId']}; pass "
+                f"--end-state {requirement['recordId']}={end_state.kind}:<how to observe it> — the brief then "
+                "asks the user to confirm it"
+            )
+        item_id = f"{end_state.kind}-{len(items[end_state.kind]) + 1:03d}"
+        line = f"{item_id} ({requirement['recordId']} · {requirement['appliesTo']}) {text}"
+        items[end_state.kind].append(line if carries else f"{line} — verify: {end_state.verify}")
+        rows.append({
+            "itemId": item_id, "requirementId": requirement["recordId"], "text": requirement["text"],
+            "kind": end_state.kind, "verify": end_state.verify, "addedByConversion": not carries,
+        })
+    return items, rows, unmapped
+
+
+def _bullets(lines: list[str]) -> list[str]:
+    return [f"- {line}" for line in lines] if lines else [NONE]
+
+
+def _confirmations(revision: Mapping[str, Any]) -> list[str]:
+    """토론에서 사용자가 이미 한 확인 — 각 항목은 확정본 안의 원 기록을 출처로 단다."""
+    rid = revision["revisionId"]
+    subject, confirmation = revision["subject"], revision["confirmation"]
+    entries = [
+        ("subject and question", subject["recordId"],
+         [f"Subject: {subject['subject']}", f"Question: {subject['question']}"]),
+        ("direction and accepted risks", confirmation["recordId"],
+         [f"Direction: {revision['direction']}", f"Risks: {confirmation['riskAcknowledgement']}"]),
+    ]
+    entries += [(f"decision {row['recordId']}", row["recordId"], [row["text"]])
+                for row in revision["decisions"] if row["author"] == USER]
+    entries += [(f"answer to {question['recordId']}", answer["recordId"], [answer["text"]])
+                for question in revision["answeredQuestions"] for answer in question["answers"]
+                if answer["author"] == USER]
+    lines = [f"Confirmations the user already gave in the discussion. Each names its record in `{rid}`.", ""]
+    for number, (topic, record_id, quoted) in enumerate(entries, start=1):
+        lines += [f"### RC-{number} — {topic}", f"- source: `{rid}` {record_id}", "- answer (verbatim):", ""]
+        lines += [f"  > {line}".rstrip() for text in quoted for line in str(text).splitlines() or [""]]
+        lines.append("")
+    return lines
+
+
+def render_brief(
+    *, discussion_key: str, revision: Mapping[str, Any], data: bytes, publication: Mapping[str, Any],
+    label: str, target: Target, end_states: list[EndState], validator: ModuleType,
+) -> tuple[str, dict[str, Any]]:
+    rid = revision["revisionId"]
+    own = _own_requirements(revision, label)
+    if not own:
+        raise FollowUpError(
+            f"{rid} has no requirement for follow-up {label!r} (common, or applies to {label!r}); "
+            f"its follow-up labels are: {', '.join(follow_up_labels(revision)) or 'none'}"
+        )
+    by_id = {row["recordId"]: row for row in own}
+    mapping: dict[str, EndState] = {}
+    for end_state in end_states:
+        if end_state.requirement_id not in by_id:
+            raise FollowUpError(f"--end-state names {end_state.requirement_id}, which is not a requirement "
+                                f"of follow-up {label!r} in {rid}")
+        if end_state.requirement_id in mapping:
+            raise FollowUpError(f"--end-state names {end_state.requirement_id} twice")
+        mapping[end_state.requirement_id] = end_state
+    items, end_rows, unmapped = _end_state_items(revision, own, mapping, validator._VERIFY_RE)
+    added = [row for row in end_rows if row["addedByConversion"]]
+    _, group, task_id = target.parts
+    path = target.brief_path(label)
+    created = revision["confirmation"]["confirmedAt"][:10]
+    confirmation = revision["confirmation"]["recordId"]
+    open_questions = [
+        f"intent-check: {row['itemId']} gives {row['requirementId']} the observation method "
+        f"\"{row['verify']}\", which {rid} does not carry — confirm with reporter"
+        for row in added
+    ]
+    open_questions += [
+        f"general: {row['recordId']} \"{_norm(row['text'])}\" has no end state in this brief yet — map it "
+        "before implementation-planning"
+        for row in unmapped
+    ]
+    open_questions += [
+        f"general: {row['recordId']} \"{_norm(row['summary'])}\" stays {row['standing']} after the discussion; "
+        f"the user accepted the remaining risk in {confirmation}"
+        for row in revision["disagreements"]
+    ]
+    open_questions += [f"general: unverified {row['kind']} {row['recordId']} — {_norm(row['detail'])}"
+                       for row in revision["unverified"]]
+    constraints = [f"out of scope: {_norm(row['text'])} — excluded by the user in {row['recordId']} of {rid}"
+                   for row in revision["scope"]["excluded"]]
+    constraints += [
+        f"out of scope: {_norm(row['text'])} — belongs to follow-up `{row['appliesTo']}` ({row['recordId']})"
+        for row in revision["requirements"] if row["appliesTo"] not in (COMMON, label)
+    ]
+    artifacts = [f"`{rid}` (`{publication['contentDigest']}`) — print it with "
+                 f"`okstra discussion revision-show {discussion_key} --revision {rid}`"]
+    if revision.get("previousRevision"):
+        previous = revision["previousRevision"]
+        artifacts.append(f"`{previous['revisionId']}` — the revision {rid} reopened: {_norm(previous['changeReason'])}")
+    fence = _fence(data.decode("utf-8"))
+    lines = [
+        "---",
+        "type: brief",
+        f"brief-id: {path.stem}",
+        f"task-id: {task_id}",
+        "parent-id: self",
+        'ticket-id: ""',
+        f"source-type: {SOURCE_TYPE}",
+        f"task-group: {group}",
+        "depth: 0",
+        f"created: {created}",
+        f"generator: {GENERATOR}",
+        f"reporter-confirmations: {'pending' if added else 'complete'}",
+        f"{FM_TASK}: {discussion_key}",
+        f"{FM_REVISION}: {rid}",
+        f"{FM_DIGEST}: {publication['contentDigest']}",
+        f"{FM_FOLLOW_UP}: {label}",
+        f"{FM_REQUIREMENTS}: {' '.join(row['recordId'] for row in own)}",
+        "---",
+        "",
+        f"# Task Brief: {group}/{path.stem}",
+        "",
+        f"> - Generated: {GENERATOR} · {created}",
+        f"> - Source type: {SOURCE_TYPE}",
+        f"> - Discussion revision: `{rid}` (follow-up `{label}`)",
+        f"> - Recommended next phase: {RECOMMENDED_PHASE}",
+        "> - Handoff contract: see `prompts/profiles/_common-contract.md` § \"Brief handoff contract\"",
+        "",
+        "## Source Material",
+        "",
+        f"### Source 1 — {SOURCE_TYPE}",
+        "",
+        f"- ref: {rid}",
+        "- fetched-via: okstra discussion revision-show",
+        f"- fetched-at: {revision['confirmation']['confirmedAt']}",
+        "- format: as-is",
+        "",
+        fence + "json",
+        data.decode("utf-8").rstrip("\n"),
+        fence,
+        "",
+        "## Context",
+        "",
+        f"The user confirmed this subject and question in `{discussion_key}` ({revision['subject']['recordId']}).",
+        "",
+        f"- Subject: {_norm(revision['subject']['subject'])}",
+        f"- Question: {_norm(revision['subject']['question'])}",
+        "",
+        f"In scope, as the user confirmed it in `{rid}`:",
+        "",
+        *_bullets([f"{_norm(row['text'])} ({row['recordId']})" for row in revision["scope"]["inScope"]]),
+        "",
+        "## Problem / Symptom",
+        "",
+        f"The discussion settled the question \"{_norm(revision['subject']['question'])}\". This follow-up "
+        f"carries the requirements of `{rid}` that are common or assigned to `{label}`.",
+        "",
+        "## Desired Outcome",
+        "",
+        f"{_norm(revision['direction'])} (the user's chosen direction, {confirmation} of `{rid}`)",
+        "",
+    ]
+    for code, heading in END_STATE_SECTIONS:
+        lines += [f"## {heading}", "", *_bullets(items[code]), ""]
+    lines += [
+        "## External Gates", "", NONE, "",
+        "## Constraints", "", *_bullets(constraints), "",
+        "## Related Artifacts", "", *_bullets(artifacts), "",
+        "## Related Task Graph", "",
+        "| From | Relation | To | Direction | Source | Impact |",
+        "|---|---|---|---|---|---|",
+        f"| {target.task_key} | follow-up-of | {discussion_key} | directed | okstra discussion follow-up-brief "
+        f"| uses {rid}; a later revision needs the user's impact review before this task adopts it |",
+        "",
+        "## Open Questions", "", *_bullets(open_questions), "",
+        "## Reporter Confirmations", "", *_confirmations(revision),
+        "## Augmentation", "",
+        "### Intent inferences", "",
+        *_bullets([f"intent-inference: {row['requirementId']} → observation method \"{row['verify']}\" "
+                   f"for {row['itemId']}" for row in added]),
+        "",
+    ]
+    text = "\n".join(lines)
+    errors = _validate_rendered([{"briefPath": path, "text": text, "taskKey": target.task_key}], validator,
+                                slugify_task_segment(group))
+    if errors:
+        raise FollowUpError("the follow-up brief failed validate-brief:\n- " + "\n- ".join(errors))
+    return text, {
+        "requirementIds": [row["recordId"] for row in own],
+        "endStates": end_rows,
+        "reporterConfirmations": "pending" if added else "complete",
+        "needsReporterConfirmation": [row["itemId"] for row in added],
+    }
+
+
+def _write_brief(path: Path, text: str, *, written_sha: str, replace: bool) -> tuple[str, str]:
+    """대상 프로젝트의 브리프를 쓴다. 이 명령이 마지막으로 쓴 바이트가 아니면 `--replace` 없이는 덮지 않는다."""
+    data = text.encode("utf-8")
+    previous = ""
+    if path.is_file():
+        current = path.read_bytes()
+        previous = _sha(current)
+        if current == data:
+            return "unchanged", previous
+        if previous != written_sha and not replace:
+            raise FollowUpError(
+                f"{path} already holds a brief this command did not write last ({previous}); "
+                "it may carry the user's confirmations — pass --replace to replace it"
+            )
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        temp.write_bytes(data)
+        os.replace(temp, path)
+    finally:
+        temp.unlink(missing_ok=True)
+    return ("replaced" if previous else "created"), previous
+
+
+# ---- 연결 기록 -------------------------------------------------------------
+
+
+def _read_links(store: DiscussionStore) -> list[dict[str, Any]]:
+    path = store.links_path
+    raw = _complete_lines(path.read_bytes()) if path.is_file() else b""
+    rows = []
+    for number, line in enumerate(raw.decode("utf-8").splitlines(), start=1):
+        if not line.strip():
+            continue
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise FollowUpError(f"{path}:{number} is not a JSON record ({exc.msg}); the link list is damaged") from exc
+        if not isinstance(row, dict) or row.get("kind") not in _PREFIX:
+            raise FollowUpError(f"{path}:{number} is not a follow-up link record")
+        rows.append(row)
+    return rows
+
+
+@contextmanager
+def _links_transaction(store: DiscussionStore) -> Iterator[list[dict[str, Any]]]:
+    with dir_flock(store.dir, _LOCK_FILENAME):
+        drop_incomplete_line(store.links_path)
+        yield _read_links(store)
+
+
+def _identity_key(kind: str, fields: Mapping[str, Any]) -> str:
+    identity = {"kind": kind, **{name: fields.get(name, "") for name in _IDENTITY_FIELDS[kind]}}
+    return _sha(json.dumps(identity, ensure_ascii=False, sort_keys=True).encode("utf-8"))
+
+
+def _existing(rows: list[dict[str, Any]], kind: str, fields: Mapping[str, Any]) -> Optional[dict[str, Any]]:
+    key = _identity_key(kind, fields)
+    return next((row for row in rows if row.get("idempotencyKey") == key), None)
+
+
+def _append(store: DiscussionStore, rows: list[dict[str, Any]], kind: str,
+            fields: dict[str, Any]) -> tuple[dict[str, Any], bool]:
+    existing = _existing(rows, kind, fields)
+    if existing is not None:
+        return existing, False
+    record = {
+        "schemaVersion": SCHEMA_VERSION,
+        "taskKey": store.task_key,
+        "recordId": f"{_PREFIX[kind]}-{1 + sum(1 for row in rows if row['kind'] == kind):04d}",
+        "kind": kind,
+        "author": USER,
+        **fields,
+        "idempotencyKey": _identity_key(kind, fields),
+        "recordedAt": _now_iso(),
+    }
+    line = json.dumps(record, ensure_ascii=False, separators=(",", ":")) + "\n"
+    with store.links_path.open("ab") as handle:
+        handle.write(line.encode("utf-8"))
+        handle.flush()
+        os.fsync(handle.fileno())
+    rows.append(record)
+    return record, True
+
+
+def _latest_link(rows: list[dict[str, Any]], target_key: str) -> Optional[dict[str, Any]]:
+    return next((row for row in reversed(rows)
+                 if row["kind"] == "link" and same_task(row["targetTaskKey"], target_key)), None)
+
+
+def _link_fields(target: Target, label: str, publication: Mapping[str, Any], path: Path,
+                 text: str, meta: Mapping[str, Any]) -> dict[str, Any]:
+    return {
+        "followUp": label,
+        "targetTaskKey": target.task_key,
+        "targetProjectRoot": str(target.project_root),
+        "briefPath": path.relative_to(target.project_root).as_posix(),
+        "revisionId": publication["revisionId"],
+        "contentDigest": publication["contentDigest"],
+        "requirementIds": list(meta["requirementIds"]),
+        "endStates": list(meta["endStates"]),
+        "briefSha256": _sha(text.encode("utf-8")),
+    }
+
+
+def _load_revision(store: DiscussionStore, revision_id: str) -> tuple[dict[str, Any], bytes, dict[str, Any]]:
+    publication, data = read_revision(store, revision_id)
+    return publication, data, json.loads(data)
+
+
+def create_follow_up(
+    store: DiscussionStore, *, revision_id: str, label: str, target: Target,
+    end_states: list[EndState], replace: bool = False,
+) -> dict[str, Any]:
+    """확정본 하나로 후속 브리프를 쓰고 연결을 기록한다. 대상 쓰기가 먼저다 — 그 뒤 중단되면 재전송이 연결만 남긴다."""
+    if not label.strip() or label == COMMON or "|" in label:
+        raise FollowUpError(f"--follow-up {label!r} must name one follow-up (not `{COMMON}`, no '|')")
+    validator = _validator()
+    publication, data, revision = _load_revision(store, revision_id)
+    path = target.brief_path(label)
+    with _links_transaction(store) as rows:
+        latest = _latest_link(rows, target.task_key)
+        pinned = brief_revision_ref(path) if path.is_file() else None
+        for followed in (latest and latest["revisionId"], pinned and pinned["revisionId"]):
+            if followed and followed != revision_id:
+                raise FollowUpError(
+                    f"{target.task_key} already follows {followed}; a follow-up never moves to another revision "
+                    f"by itself — adopt {revision_id} with `okstra discussion apply {store.task_key} --revision "
+                    f"{revision_id} --target-task {target.task_key} --choice adopt`"
+                )
+        if latest is not None and latest["followUp"] != label:
+            raise FollowUpError(f"{target.task_key} is already the follow-up `{latest['followUp']}` of this discussion")
+        text, meta = render_brief(discussion_key=store.task_key, revision=revision, data=data,
+                                  publication=publication, label=label, target=target, end_states=end_states,
+                                  validator=validator)
+        status, previous = _write_brief(path, text, written_sha=latest["briefSha256"] if latest else "",
+                                        replace=replace)
+        record, created = _append(store, rows, "link", _link_fields(target, label, publication, path, text, meta))
+    pending = meta["reporterConfirmations"] == "pending"
+    return {
+        "created": created,
+        "link": record,
+        "briefPath": str(path),
+        "briefStatus": status,
+        "previousBriefSha256": previous,
+        "recommendedPhase": RECOMMENDED_PHASE,
+        **meta,
+        "next": (
+            "The conversion added observation methods the discussion did not carry: confirm the intent-check "
+            "rows with the user (okstra-brief-gen Step 6.5) before the first run; prepare refuses a pending brief."
+            if pending else
+            f"Start the follow-up at {RECOMMENDED_PHASE} with --task-type {RECOMMENDED_PHASE} --task-brief {path}."
+        ),
+    }
+
+
+# ---- 변경 내용과 영향 검토 -------------------------------------------------
+
+
+def _delta(old: list[Mapping[str, Any]], new: list[Mapping[str, Any]],
+           key: Callable[[Mapping[str, Any]], Any], *fields: str) -> dict[str, list[dict[str, Any]]]:
+    before, after = {key(row): row for row in old}, {key(row): row for row in new}
+
+    def view(row: Mapping[str, Any]) -> dict[str, Any]:
+        return {"recordId": row.get("recordId"), **{name: row.get(name) for name in fields}}
+
+    return {
+        "added": [view(row) for k, row in after.items() if k not in before],
+        "removed": [view(row) for k, row in before.items() if k not in after],
+    }
+
+
+def _item_delta(old: list[Mapping[str, Any]], new: list[Mapping[str, Any]],
+                key: Callable[[Mapping[str, Any]], Any], withdrawals: Mapping[str, Mapping[str, Any]],
+                *fields: str) -> dict[str, list[dict[str, Any]]]:
+    """요구사항·범위의 변화 — 빠진 항목에는 새 확정본이 기록한 사용자의 철회 사유를, 남은 항목은 `carried` 로 싣는다."""
+    delta = _delta(old, new, key, *fields)
+    before = {key(row) for row in old}
+    delta["removed"] = [
+        {**row, "withdrawal": withdrawals.get(row["recordId"])} for row in delta["removed"]
+    ]
+    delta["carried"] = [
+        {"recordId": row.get("recordId"), **{name: row.get(name) for name in fields}}
+        for row in new if key(row) in before
+    ]
+    return delta
+
+
+def revision_changes(old: Mapping[str, Any], new: Mapping[str, Any], label: str = "") -> dict[str, Any]:
+    """두 확정본 사이에 바뀐 것. `label` 이 있으면 그 후속 작업의 요구사항(공통 포함)만 본다."""
+    def requirements(revision: Mapping[str, Any]) -> list[Mapping[str, Any]]:
+        return _own_requirements(revision, label) if label else revision["requirements"]
+
+    def text(row: Mapping[str, Any]) -> str:
+        return _norm(row.get("text"))
+
+    withdrawals = {row["recordId"]: row["withdrawal"]
+                   for row in (new.get("itemChanges") or {}).get("withdrawn", [])}
+    changes: dict[str, Any] = {
+        "from": old["revisionId"],
+        "to": new["revisionId"],
+        "followUp": label or None,
+        "changeReason": (new.get("previousRevision") or {}).get("changeReason"),
+        "requirements": _item_delta(requirements(old), requirements(new),
+                                    lambda row: (row["appliesTo"], text(row)), withdrawals, "appliesTo", "text"),
+        "inScope": _item_delta(old["scope"]["inScope"], new["scope"]["inScope"], text, withdrawals, "text"),
+        "excluded": _item_delta(old["scope"]["excluded"], new["scope"]["excluded"], text, withdrawals, "text"),
+        "decisions": _delta(old["decisions"], new["decisions"], text, "text"),
+        "disagreements": _delta(old["disagreements"], new["disagreements"],
+                                lambda row: _norm(row.get("summary")), "summary", "standing"),
+        "unverified": _delta(old["unverified"], new["unverified"],
+                             lambda row: (row.get("kind"), _norm(row.get("detail"))), "kind", "detail"),
+        "direction": (
+            {"from": old["direction"], "to": new["direction"]}
+            if _norm(old["direction"]) != _norm(new["direction"]) else None
+        ),
+    }
+    changes["changed"] = changes["direction"] is not None or any(
+        part["added"] or part["removed"]
+        for part in changes.values()
+        if isinstance(part, dict) and "added" in part
+    )
+    return changes
+
+
+def impact(store: DiscussionStore, *, from_revision: str, to_revision: str, label: str = "") -> dict[str, Any]:
+    _, _, old = _load_revision(store, from_revision)
+    _, _, new = _load_revision(store, to_revision)
+    return revision_changes(old, new, label)
+
+
+def _planning_ref(target: Target) -> RunRef:
+    _, group, task_id = target.parts
+    return RunRef(project_root=target.project_root, task_group=group, task_id=task_id,
+                  task_type="implementation-planning")
+
+
+def _plan_reports(target: Target) -> list[Path]:
+    reports_dir = _planning_ref(target).reports_dir
+    return list_implementation_planning_reports(reports_dir) if reports_dir.is_dir() else []
+
+
+def _plan_state(target: Target) -> tuple[bool, Optional[str]]:
+    """대상 task 에 계획(완료된 planning 보고서, 또는 준비된 planning run)이 있는가, 그 계획이 쓴 확정본."""
+    ref = _planning_ref(target)
+    reports = _plan_reports(target)
+    manifests = ref.run_dir / "manifests"
+    inputs = sorted(manifests.glob("run-inputs-*.json")) if manifests.is_dir() else []
+    basis = None
+    if inputs:
+        payload = load_owned_object(inputs[-1], artifact="run inputs")
+        basis = ((payload.get("inputs") or {}).get("discussionRevisionRef") or {}).get("revisionId")
+    return bool(reports or inputs), basis
+
+
+def _amended_plan(target: Target, routed: Mapping[str, Any]) -> tuple[Optional[Path], str]:
+    """계획 수정 경로로 보낸 뒤 사용자가 승인한 planning 보고서 — 없으면 무엇이 없는지.
+
+    근거는 보고서의 `frontmatter.approved` 다. 구현 run 이 받는 계획도 승인된 계획뿐이라
+    (`run._validate_approved_plan`), 승인 전의 새 보고서로 고정을 옮기면 브리프와 실제로 따르는 계획이 갈린다.
+    """
+    anchor = int(routed["planReportSeq"])
+    newer = [report for report in _plan_reports(target) if implementation_planning_report_seq(report) > anchor]
+    for report in newer:
+        if plan_is_approved(load_owned_object(report, artifact="implementation-planning report")):
+            return report, ""
+    seen = ", ".join(f"{report.name} (not approved)" for report in newer) or "none"
+    return None, (
+        f"no implementation-planning report of {target.task_key} newer than run {anchor:03d} — the latest when "
+        f"{routed['recordId']} routed the adoption — has `approved: true`; newer reports: {seen}. Request the "
+        "plan revision, re-run implementation-planning and let the user approve the amended plan first"
+    )
+
+
+def _applies(rows: list[dict[str, Any]], kind: str = "apply") -> dict[tuple[str, str], dict[str, Any]]:
+    return {(row["revisionId"], row["targetTaskKey"].lower()): row for row in rows if row["kind"] == kind}
+
+
+def _target_view(
+    store: DiscussionStore, link: Mapping[str, Any], publications: Mapping[str, Mapping[str, Any]],
+    latest: Optional[str], applies: Mapping[tuple[str, str], Mapping[str, Any]],
+    amendments: Mapping[tuple[str, str], Mapping[str, Any]], revisions: Callable[[str], dict[str, Any]],
+) -> dict[str, Any]:
+    view: dict[str, Any] = {
+        "followUp": link["followUp"], "targetTaskKey": link["targetTaskKey"],
+        "targetProjectRoot": link["targetProjectRoot"], "briefPath": link["briefPath"],
+        "linkedRevision": link["revisionId"], "latestRevision": latest,
+    }
+    target = Target(link["targetTaskKey"], Path(link["targetProjectRoot"]))
+    brief = target.project_root / link["briefPath"]
+    try:
+        ref = brief_revision_ref(brief) if brief.is_file() else None
+        if ref is None:
+            return {**view, "state": "unknown",
+                    "reason": f"{brief} is missing or names no discussion revision; the target cannot be read"}
+        publication = publications.get(ref["revisionId"])
+        if not same_task(ref["discussionTaskKey"], store.task_key) or publication is None \
+                or publication["contentDigest"] != ref["contentDigest"]:
+            return {**view, "state": "unknown",
+                    "reason": f"{brief} pins {ref['revisionId']} ({ref['contentDigest']}), which is not a "
+                              "published revision of this discussion"}
+        has_plan, basis = _plan_state(target)
+    except (OSError, JsonBoundaryError) as exc:
+        return {**view, "state": "unknown", "reason": f"the target cannot be read: {exc}"}
+    view.update({"pinnedRevision": ref["revisionId"], "requirementIds": ref["requirementIds"],
+                 "hasPlan": has_plan, "planBasis": basis})
+    amendment = amendments.get((ref["revisionId"], link["targetTaskKey"].lower()))
+    if amendment is not None:
+        view["amendmentRecord"] = amendment["recordId"]
+    if latest is None or ref["revisionId"] == latest:
+        return {**view, "state": "current"}
+    decision = applies.get((latest, link["targetTaskKey"].lower()))
+    state = ("needs-impact-review" if decision is None
+             else "kept" if decision["choice"] == "keep" else "amendment-pending")
+    if state == "amendment-pending" and decision.get("result") == ROUTED:
+        try:
+            plan, missing = _amended_plan(target, decision)
+        except (OSError, JsonBoundaryError) as exc:
+            return {**view, "state": "unknown", "reason": f"the target's plan cannot be read: {exc}"}
+        view["amendedPlan"] = plan.relative_to(target.project_root).as_posix() if plan else None
+        view["next"] = (
+            f"okstra discussion complete-amendment {store.task_key} --revision {latest} "
+            f"--target-task {link['targetTaskKey']}" if plan else missing
+        )
+    changes = revision_changes(revisions(ref["revisionId"]), revisions(latest), link["followUp"])
+    return {**view, "state": state, "applyRecord": decision["recordId"] if decision else None, "changes": changes}
+
+
+def links(store: DiscussionStore) -> dict[str, Any]:
+    """연결된 후속 작업과 영향 검토 상태 — 매번 대상의 브리프에서 다시 읽고, 어디에도 쓰지 않는다."""
+    draft = project_draft(store)
+    publications = {row["revisionId"]: row for row in draft["revisions"]}
+    latest = draft["revisions"][-1]["revisionId"] if draft["revisions"] else None
+    cache: dict[str, dict[str, Any]] = {}
+
+    def revision(revision_id: str) -> dict[str, Any]:
+        if revision_id not in cache:
+            cache[revision_id] = _load_revision(store, revision_id)[2]
+        return cache[revision_id]
+
+    rows = _read_links(store)
+    targets: dict[str, dict[str, Any]] = {}
+    for row in rows:
+        if row["kind"] == "link":
+            targets[row["targetTaskKey"].lower()] = row
+    applies = _applies(rows)
+    amendments = _applies(rows, "amendment")
+    views = [_target_view(store, link, publications, latest, applies, amendments, revision)
+             for link in targets.values()]
+    labels = follow_up_labels(revision(latest)) if latest else []
+    return {
+        "latestRevision": latest,
+        "followUps": views,
+        "unlinkedFollowUps": [label for label in labels if label not in {v["followUp"] for v in views}],
+    }
+
+
+# ---- 적용 ------------------------------------------------------------------
+
+
+def _amendment_route(store: DiscussionStore, target: Target, previous: str, revision_id: str,
+                     label: str) -> dict[str, Any]:
+    return {
+        "path": "plan-amendment",
+        "reason": f"{target.task_key} already has an implementation-planning plan; applying {revision_id} never "
+                  "rewrites an approved plan, its brief or its source",
+        "steps": [
+            f"okstra discussion impact {store.task_key} --from {previous} --to {revision_id} --follow-up {label}",
+            "record the change as a `revision-requested` plan decision on the target's latest "
+            "implementation-planning report (okstra-user-response, `okstra user-response plan-decision "
+            "--status revision-requested`)",
+            "re-run implementation-planning for the target with --clarification-response <that sidecar>",
+            "after the user approves the amended plan, move the brief to the revision with "
+            f"`okstra discussion complete-amendment {store.task_key} --revision {revision_id} "
+            f"--target-task {target.task_key}`",
+        ],
+    }
+
+
+def _rewrite_brief(
+    store: DiscussionStore, rows: list[dict[str, Any]], link: Mapping[str, Any], target: Target, path: Path,
+    publication: Mapping[str, Any], data: bytes, revision: Mapping[str, Any], end_states: list[EndState],
+    replace: bool,
+) -> dict[str, Any]:
+    """대상 브리프를 새 확정본으로 다시 쓰고 연결을 남긴다. 끝 상태는 요구사항 문장으로 이어받고 `--end-state` 가 더한다."""
+    reused = {_norm(row["text"]): row for row in link.get("endStates") or []}
+    explicit = {row.requirement_id: row for row in end_states}
+    own = _own_requirements(revision, link["followUp"])
+    unknown = sorted(set(explicit) - {row["recordId"] for row in own})
+    if unknown:
+        raise FollowUpError(f"--end-state names {', '.join(unknown)}, which is not a requirement of "
+                            f"follow-up {link['followUp']!r} in {revision['revisionId']}")
+    mapped = []
+    for requirement in own:
+        row = explicit.get(requirement["recordId"]) or reused.get(_norm(requirement["text"]))
+        if isinstance(row, EndState):
+            mapped.append(row)
+        elif row is not None:
+            mapped.append(EndState(requirement["recordId"], row["kind"], row["verify"]))
+    text, meta = render_brief(discussion_key=store.task_key, revision=revision, data=data,
+                              publication=publication, label=link["followUp"], target=target,
+                              end_states=mapped, validator=_validator())
+    status, previous_sha = _write_brief(path, text, written_sha=link["briefSha256"], replace=replace)
+    new_link, _ = _append(store, rows, "link", _link_fields(target, link["followUp"], publication, path, text, meta))
+    return {"briefStatus": status, "previousBriefSha256": previous_sha, "link": new_link["recordId"],
+            "reporterConfirmations": meta["reporterConfirmations"],
+            "needsReporterConfirmation": meta["needsReporterConfirmation"]}
+
+
+def apply_revision(
+    store: DiscussionStore, *, revision_id: str, target_key: str, choice: str,
+    end_states: list[EndState], replace: bool = False,
+) -> dict[str, Any]:
+    """사용자가 고른 대상에만 새 확정본을 적용한다. 같은 요청의 재전송은 저장된 적용 기록을 돌려준다."""
+    if choice not in CHOICES:
+        raise FollowUpError(f"--choice must be one of {', '.join(CHOICES)}")
+    draft = read_draft(store)
+    latest = draft["revisions"][-1]["revisionId"] if draft["revisions"] else None
+    if revision_id != latest:
+        raise FollowUpError(f"apply names {revision_id}, but the latest published revision is {latest or 'none'}")
+    publication, data, revision = _load_revision(store, revision_id)
+    with _links_transaction(store) as rows:
+        fields_key = {"targetTaskKey": target_key, "revisionId": revision_id, "choice": choice}
+        existing = _existing(rows, "apply", fields_key)
+        if existing is not None:
+            return {"created": False, "apply": existing}
+        earlier = _applies(rows).get((revision_id, target_key.lower()))
+        if earlier is not None:
+            raise FollowUpError(f"{target_key} already has the user's choice {earlier['choice']!r} for "
+                                f"{revision_id} ({earlier['recordId']})")
+        link = _latest_link(rows, target_key)
+        if link is None:
+            raise FollowUpError(f"no follow-up {target_key} is linked to {store.task_key}")
+        target = Target(link["targetTaskKey"], Path(link["targetProjectRoot"]))
+        path = target.project_root / link["briefPath"]
+        try:
+            pinned = brief_revision_ref(path) if path.is_file() else None
+            has_plan, _ = _plan_state(target)
+            reports = _plan_reports(target)
+        except (OSError, JsonBoundaryError) as exc:
+            raise FollowUpError(f"{target_key} cannot be read ({exc}); its state is unknown") from exc
+        if pinned is None:
+            raise FollowUpError(f"{path} is missing or names no revision; the state of {target_key} is unknown")
+        previous = pinned["revisionId"]
+        if previous == revision_id:
+            # 앞선 적용이 대상을 쓰고 기록 전에 끊긴 경우 — 이전 확정본은 연결 기록에 남아 있다.
+            before = next((row for row in reversed(rows) if row["kind"] == "link"
+                           and same_task(row["targetTaskKey"], target_key) and row["revisionId"] != revision_id),
+                          None)
+            if before is None or choice != "adopt":
+                raise FollowUpError(f"{target_key} already uses {revision_id}")
+            previous = before["revisionId"]
+        result: dict[str, Any] = {}
+        if choice == "keep":
+            outcome = "kept"
+        elif has_plan:
+            outcome = ROUTED
+            result["route"] = _amendment_route(store, target, previous, revision_id, link["followUp"])
+            result["planReport"] = reports[0].relative_to(target.project_root).as_posix() if reports else None
+            result["planReportSeq"] = implementation_planning_report_seq(reports[0]) if reports else 0
+        else:
+            outcome = "applied"
+            result.update(_rewrite_brief(store, rows, link, target, path, publication, data, revision,
+                                         end_states, replace))
+            result["recommendedPhase"] = RECOMMENDED_PHASE
+        record, created = _append(store, rows, "apply", {
+            **fields_key, "followUp": link["followUp"], "previousRevision": previous,
+            "result": outcome, **result,
+        })
+    return {"created": created, "apply": record}
+
+
+def complete_amendment(
+    store: DiscussionStore, *, revision_id: str, target_key: str, end_states: list[EndState], replace: bool = False,
+) -> dict[str, Any]:
+    """계획 수정 경로로 보낸 채택을 끝낸다 — 그 뒤 사용자가 승인한 계획이 있을 때만 브리프 고정을 옮긴다.
+
+    계획·소스는 읽기만 하고, 승인은 사용자가 계획 쪽 경로에서 한 것만 근거로 쓴다.
+    """
+    publication, data, revision = _load_revision(store, revision_id)
+    with _links_transaction(store) as rows:
+        fields_key = {"targetTaskKey": target_key, "revisionId": revision_id}
+        existing = _existing(rows, "amendment", fields_key)
+        if existing is not None:
+            return {"created": False, "amendment": existing}
+        routed = _applies(rows).get((revision_id, target_key.lower()))
+        if routed is None or routed.get("result") != ROUTED:
+            raise FollowUpError(
+                f"{target_key} has no adoption of {revision_id} routed to plan amendment; record the user's choice "
+                f"with `okstra discussion apply {store.task_key} --revision {revision_id} --target-task {target_key} "
+                "--choice adopt` first"
+            )
+        link = _latest_link(rows, target_key)
+        target = Target(link["targetTaskKey"], Path(link["targetProjectRoot"]))
+        path = target.project_root / link["briefPath"]
+        try:
+            pinned = brief_revision_ref(path) if path.is_file() else None
+            plan, missing = _amended_plan(target, routed)
+        except (OSError, JsonBoundaryError) as exc:
+            raise FollowUpError(f"{target_key} cannot be read ({exc}); its state is unknown") from exc
+        if pinned is None:
+            raise FollowUpError(f"{path} is missing or names no revision; the state of {target_key} is unknown")
+        if pinned["revisionId"] not in (routed["previousRevision"], revision_id):
+            raise FollowUpError(
+                f"{path} pins {pinned['revisionId']}, not {routed['previousRevision']} that {routed['recordId']} "
+                "routed from; the brief changed since the adoption was routed"
+            )
+        if plan is None:
+            raise FollowUpError(missing)
+        result = _rewrite_brief(store, rows, link, target, path, publication, data, revision, end_states, replace)
+        record, created = _append(store, rows, "amendment", {
+            **fields_key, "followUp": link["followUp"], "previousRevision": routed["previousRevision"],
+            "applyRecord": routed["recordId"], "planReport": plan.relative_to(target.project_root).as_posix(),
+            "planReportSeq": implementation_planning_report_seq(plan), "result": "applied", **result,
+        })
+    return {"created": created, "amendment": record}