okstra 0.178.0 → 0.179.1

package/runtime/python/okstra_ctl/run.py

@@ -32,6 +32,7 @@ from okstra_project import project_json_path, upsert_project_json
 from okstra_project.state import slugify
 from . import fix_cycles
 from .analysis_packet import build_analysis_packet
+from .stage_ledger import build_stage_ledger, render_stage_ledger
 from .analysis_inputs import (
     ANALYSIS_TASK_TYPES,
     AnalysisInputError,
@@ -66,7 +67,11 @@ from .material import (
     resolve_related_tasks,
 )
 from .final_report_schema import load_schema_version
-from .final_report_paths import final_report_data_path as _final_report_data_path
+from .final_report_paths import (
+    final_report_data_path as _final_report_data_path,
+    final_report_markdown_path as _final_report_markdown_path,
+    require_approved_plan_record as _require_approved_plan_record_path,
+)
 from .lead_events import LeadEvent, append_lead_event
 from .assignment_environment import load_assignment_context
 from .assignment_resolver import (
@@ -197,9 +202,9 @@ from .scope_provenance import brief_end_state_id_sequence
 # Frontmatter approval-flag matcher.
 #
 # Final-report 의 YAML frontmatter 안에서 `approved: true` / `approved: false`
-# 한 줄만 식별한다. report-writer 가 항상 이 한 줄을 출력하고, 사용자가
-# 직접 편집하거나 `--approve` CLI 가 이 줄만 toggle 한다. 본문(body) 의 다른
-# `approved:` 등장과 충돌하지 않도록 호출자는 frontmatter 블록을 먼저 추출
+# 한 줄만 식별한다. schema-v1 에서는 이 줄이 정본이고, schema-v2 에서는
+# 정본 `frontmatter.approved` 의 표시다. 본문(body) 의 다른 `approved:` 등장과
+# 충돌하지 않도록 호출자는 frontmatter 블록을 먼저 추출
 # (`_extract_frontmatter_block`) 한 뒤 이 패턴을 적용한다.
 APPROVED_FRONTMATTER_PATTERN = re.compile(
     r"^approved:[ \t]+(true|false)[ \t]*$",
@@ -216,16 +221,14 @@ BLOCKING_PLAN_BODY_GATES = {"blocked-by-disagreement", "aborted-non-result"}
 #
 # `approved:` 바로 아래 줄의 `implementation-option:` 한 줄을 식별한다.
 # report-writer 가 빈 값으로 항상 emit 하므로 라인은 존재하되 값은 비어 있을
-# 수 있다. `--implementation-option <name>` CLI 가 이 줄의 값만 치환한다.
-# 값이 비면 implementation 은 plan 의 `Recommended Option` 으로 폴백한다.
+# 수 있다. `--implementation-option <name>` CLI 가 schema-v1 에서 이 줄의
+# 값만 치환한다. schema-v2 는 정본 `frontmatter.implementationOption` 을 쓰고
+# 열람본을 다시 렌더한다. 값이 비면 implementation 은 plan 의
+# `Recommended Option` 으로 폴백한다.
 IMPLEMENTATION_OPTION_FRONTMATTER_PATTERN = re.compile(
     r"^implementation-option:[ \t]*(.*)$",
     re.MULTILINE,
 )
-SELECTED_DIRECTION_FRONTMATTER_PATTERN = re.compile(
-    r"^selected-direction-ref:[ \t]*(.*)$",
-    re.MULTILINE,
-)
 
 # validators/validate-run.py:_FRONTMATTER_BLOCK_RE 의 미러 — 선행 BOM/빈 줄을
 # 허용해 두 모듈이 같은 리포트의 frontmatter 게이트를 동일하게 판정하게 한다.
@@ -267,40 +270,11 @@ def _data_json_gate_result(data: dict) -> str:
     return str(verification.get("gateResult") or "").strip().lower()
 
 
-def _reject_blocking_plan_body_gate(path: Path, body: str, *, action: str) -> None:
-    gate_match = PLAN_BODY_GATE_PATTERN.search(body)
-    if gate_match:
-        gate_value = gate_match.group("value").strip().lower()
-        if gate_value in BLOCKING_PLAN_BODY_GATES:
-            raise PrepareError(
-                f"{action} rejected because approved plan Gate result is "
-                f"`{gate_value}`: {path}\n"
-                "  resolve the plan-body verification disagreement and regenerate "
-                "the implementation-planning report before approval."
-            )
-
+def _record_approved_flag(path: Path) -> bool | None:
+    """정본 `frontmatter.approved`. 정본이 없으면(schema-v1) None."""
     loaded = _load_final_report_data_if_present(path)
     if loaded is None:
-        return
-    data_path, data = loaded
-    data_gate = _data_json_gate_result(data)
-    if data_gate in BLOCKING_PLAN_BODY_GATES:
-        raise PrepareError(
-            f"{action} rejected because approved plan data.json Gate result is "
-            f"`{data_gate}`: {data_path}\n"
-            "  data.json is the final-report source of truth; regenerate the "
-            "report after resolving the verification disagreement."
-        )
-
-
-def _validate_data_json_approval_consistency(
-    path: Path,
-    *,
-    markdown_approved: bool,
-) -> None:
-    loaded = _load_final_report_data_if_present(path)
-    if loaded is None:
-        return
+        return None
     data_path, data = loaded
     frontmatter = data.get("frontmatter")
     if not isinstance(frontmatter, dict) or "approved" not in frontmatter:
@@ -312,15 +286,42 @@ def _validate_data_json_approval_consistency(
         raise PrepareError(
             f"approved plan data.json frontmatter.approved is not boolean: {data_path}"
         )
-    if data_approved != markdown_approved:
+    return data_approved
+
+
+def _unapproved_plan_message(path: str, displayed: str) -> str:
+    return (
+        f"approved plan is not yet approved (frontmatter `approved: {displayed}`): "
+        f"{path}\n"
+        "  re-run okstra with `--approve`, or confirm approval in the "
+        "in-session wizard.\n"
+        "  resolve any `Blocks=approval` rows in `## 1. Clarification Items` first."
+    )
+
+
+def _reject_blocking_plan_body_gate(path: Path, body: str, *, action: str) -> None:
+    loaded = _load_final_report_data_if_present(path)
+    if loaded is not None:
+        data_path, data = loaded
+        data_gate = _data_json_gate_result(data)
+        if data_gate in BLOCKING_PLAN_BODY_GATES:
+            raise PrepareError(
+                f"{action} rejected because approved plan data.json Gate result is "
+                f"`{data_gate}`: {data_path}\n"
+                "  resolve the plan-body verification disagreement and regenerate "
+                "the implementation-planning report before approval."
+            )
+        return
+    gate_match = PLAN_BODY_GATE_PATTERN.search(body)
+    if not gate_match:
+        return
+    gate_value = gate_match.group("value").strip().lower()
+    if gate_value in BLOCKING_PLAN_BODY_GATES:
         raise PrepareError(
-            "approved plan markdown frontmatter and data.json disagree on "
-            f"`approved`: markdown={str(markdown_approved).lower()}, "
-            f"data.json={str(data_approved).lower()}\n"
-            f"  markdown: {path}\n"
-            f"  data.json: {data_path}\n"
-            "  regenerate the report from data.json or use `okstra --approve` "
-            "so the source of truth is updated first."
+            f"{action} rejected because approved plan Gate result is "
+            f"`{gate_value}`: {path}\n"
+            "  resolve the plan-body verification disagreement and regenerate "
+            "the implementation-planning report before approval."
         )
 
 
@@ -361,24 +362,10 @@ def _validate_approved_plan_conformance(path: Path) -> None:
     )
 
 
-def _set_data_json_approved_true_if_present(path: Path) -> bool:
-    loaded = _load_final_report_data_if_present(path)
-    if loaded is None:
-        return False
-    data_path, data = loaded
-    data_gate = _data_json_gate_result(data)
-    if data_gate in BLOCKING_PLAN_BODY_GATES:
-        raise PrepareError(
-            f"--approve rejected because approved plan data.json Gate result is "
-            f"`{data_gate}`: {data_path}"
-        )
-    frontmatter = data.setdefault("frontmatter", {})
-    if not isinstance(frontmatter, dict):
-        raise PrepareError(
-            f"approved plan data.json frontmatter must be an object: {data_path}"
-        )
-    frontmatter["approved"] = True
-
+def _commit_data_json_and_rerender(
+    record_path: Path, data: dict, *, action: str
+) -> None:
+    """정본을 쓰고 전문 열람본을 그 정본에서 다시 렌더한다."""
     try:
         from .render_final_report import (
             FinalReportRenderError,
@@ -392,11 +379,12 @@ def _set_data_json_approved_true_if_present(path: Path) -> bool:
         )
     except FinalReportRenderError as exc:
         raise PrepareError(
-            f"--approve could not re-render approved plan from data.json: {exc}"
+            f"{action} could not re-render approved plan from data.json: {exc}"
         ) from exc
 
-    data_tmp = data_path.with_suffix(data_path.suffix + f".tmp.{os.getpid()}")
-    md_tmp = path.with_suffix(path.suffix + f".tmp.{os.getpid()}")
+    md_path = _final_report_markdown_path(record_path)
+    data_tmp = record_path.with_suffix(record_path.suffix + f".tmp.{os.getpid()}")
+    md_tmp = md_path.with_suffix(md_path.suffix + f".tmp.{os.getpid()}")
     data_tmp.write_text(
         json.dumps(data, ensure_ascii=False, indent=2) + "\n",
         encoding="utf-8",
@@ -404,16 +392,34 @@ def _set_data_json_approved_true_if_present(path: Path) -> bool:
     md_tmp.write_text(rendered, encoding="utf-8")
     # 두 파일을 같이 atomic 하게 commit 할 수 없으므로, 첫 replace 직전의
     # data.json 바이트를 보관했다가 markdown replace 가 실패하면 data.json 을
-    # 되돌린다. 이렇게 하면 부분 실패가 "둘 다 approved 이전(consistent)" 상태로
-    # 수렴해 이후 _validate_data_json_approval_consistency 의 hard-fail 을 막는다
-    # (남는 불일치 창은 두 replace 사이의 hard process kill 뿐).
-    data_prev = data_path.read_bytes()
-    data_tmp.replace(data_path)
+    # 되돌린다. 남는 불일치 창은 두 replace 사이의 hard process kill 뿐이다.
+    data_prev = record_path.read_bytes()
+    data_tmp.replace(record_path)
     try:
-        md_tmp.replace(path)
+        md_tmp.replace(md_path)
     except OSError:
-        data_path.write_bytes(data_prev)
+        record_path.write_bytes(data_prev)
         raise
+
+
+def _set_data_json_approved_true_if_present(path: Path) -> bool:
+    loaded = _load_final_report_data_if_present(path)
+    if loaded is None:
+        return False
+    data_path, data = loaded
+    data_gate = _data_json_gate_result(data)
+    if data_gate in BLOCKING_PLAN_BODY_GATES:
+        raise PrepareError(
+            f"--approve rejected because approved plan data.json Gate result is "
+            f"`{data_gate}`: {data_path}"
+        )
+    frontmatter = data.setdefault("frontmatter", {})
+    if not isinstance(frontmatter, dict):
+        raise PrepareError(
+            f"approved plan data.json frontmatter must be an object: {data_path}"
+        )
+    frontmatter["approved"] = True
+    _commit_data_json_and_rerender(data_path, data, action="--approve")
     return True
 
 
@@ -521,35 +527,19 @@ def _default(name: str, fallback: str) -> str:
     return os.environ.get(name, "") or fallback
 
 
+def _approved_plan_record(path: str) -> Path:
+    try:
+        return _require_approved_plan_record_path(Path(path))
+    except ValueError as exc:
+        raise PrepareError(str(exc)) from exc
+
+
 def _validate_approved_plan(path: str) -> None:
-    p = Path(path)
-    if not p.is_file():
-        raise PrepareError(f"approved plan file not found: {path}")
-    body = p.read_text(encoding="utf-8", errors="replace")
-    frontmatter = _extract_frontmatter_block(body)
-    if frontmatter is None:
-        raise PrepareError(
-            f"approved plan has no YAML frontmatter block: {path}\n"
-            "  expected the report to begin with `---\\n...\\n---\\n`. "
-            "report-writer worker emits this header on every run; "
-            "regenerate the report if the header is missing."
-        )
-    m = APPROVED_FRONTMATTER_PATTERN.search(frontmatter)
-    if not m:
-        raise PrepareError(
-            f"approved plan frontmatter has no `approved:` field: {path}\n"
-            "  expected a single line of the form `approved: true` "
-            "(or `approved: false` for the unflipped state)."
-        )
-    if m.group(1).lower() != "true":
-        raise PrepareError(
-            f"approved plan is not yet approved (frontmatter `approved: {m.group(1)}`): {path}\n"
-            "  open the report and change the frontmatter line to `approved: true`, "
-            "or re-run okstra with `--approve` to flip it from the CLI.\n"
-            "  resolve any `Blocks=approval` rows in `## 1. Clarification Items` first."
-        )
-    _reject_blocking_plan_body_gate(p, body, action="approved plan validation")
-    _validate_data_json_approval_consistency(p, markdown_approved=True)
+    p = _approved_plan_record(path)
+    record_approved = _record_approved_flag(p)
+    if record_approved is not True:
+        raise PrepareError(_unapproved_plan_message(str(p), "false"))
+    _reject_blocking_plan_body_gate(p, "", action="approved plan validation")
     _validate_approved_plan_conformance(p)
     # frontmatter approved == true 상태. §1 Clarification Items 의
     # Blocks=approval 행이 아직 open/answered 면 승인을 무효화한다.
@@ -607,129 +597,37 @@ def _parse_stage_map_into_ctx(plan_path: str) -> list:
         ) from exc
 
 
-def _apply_cli_approval(path: str) -> str:
-    """`--approve` 가 지정된 경우 approved-plan 의 frontmatter `approved` 를 true 로 토글.
+def _apply_cli_approval(path: str) -> None:
+    """`--approve` 가 지정된 경우 정본 `frontmatter.approved` 를 true 로 토글.
 
-    동작 요약:
-      - frontmatter 에 `approved: false` 가 있으면 `approved: true` 로 교체하고
-        audit 라인을 append → `"frontmatter-flipped"` 반환.
-      - 이미 `approved: true` 면 한 번도 기록되지 않은 audit 라인만 append →
-        `"already-approved-audit-appended"`, 이미 동일 audit 가 있으면
-        `"already-approved"` 로 no-op.
-      - frontmatter 가 없거나 `approved:` 라인이 없으면 PrepareError.
-
-    Idempotent: 동일 audit 라인은 한 번만 기록된다.
+    정본을 쓰고 열람본을 다시 렌더한다. 이미 true 면 아무 것도 쓰지 않는다.
+    schema-v1 계획은 정본이 없어 `--approved-plan` 으로 받을 수 없다.
     """
-    p = Path(path)
-    if not p.is_file():
-        raise PrepareError(f"approved plan file not found: {path}")
-    body = p.read_text(encoding="utf-8", errors="replace")
-    frontmatter = _extract_frontmatter_block(body)
-    if frontmatter is None:
-        raise PrepareError(
-            f"--approve was given but the approved-plan file has no YAML frontmatter: {path}\n"
-            "  expected the report to begin with `---\\n...\\n---\\n`."
-        )
-    m = APPROVED_FRONTMATTER_PATTERN.search(frontmatter)
-    if not m:
+    p = _approved_plan_record(path)
+    _reject_blocking_plan_body_gate(p, "", action="--approve")
+    if _record_approved_flag(p) is True:
+        return
+    if not _set_data_json_approved_true_if_present(p):
         raise PrepareError(
-            f"--approve was given but the approved-plan frontmatter has no `approved:` field: {path}\n"
-            "  expected a single line of the form `approved: false` "
-            "(report-writer worker emits this by default)."
+            f"--approve found a report record but could not update it: {p}"
         )
-    _reject_blocking_plan_body_gate(p, body, action="--approve")
 
-    audit_iso = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-    audit_line = (
-        f"- 승인 일시 (CLI ack): {audit_iso} — recorded by `okstra --approve` "
-        "(user CLI invocation treated as approval signal)"
-    )
 
-    rendered_from_data = False
-    if m.group(1).lower() != "true":
-        rendered_from_data = _set_data_json_approved_true_if_present(p)
-        if rendered_from_data:
-            body = p.read_text(encoding="utf-8", errors="replace")
-            frontmatter = _extract_frontmatter_block(body) or ""
-            m = APPROVED_FRONTMATTER_PATTERN.search(frontmatter)
-            if not m:
-                raise PrepareError(
-                    f"--approve re-rendered the approved-plan but the markdown "
-                    f"frontmatter has no `approved:` field: {path}"
-                )
-
-    if m.group(1).lower() == "true":
-        if audit_line.split(" — ")[1] in body:
-            return "already-approved"
-        new_body = body.rstrip("\n") + "\n" + audit_line + "\n"
-        p.write_text(new_body, encoding="utf-8")
-        if rendered_from_data:
-            return "frontmatter-flipped"
-        return "already-approved-audit-appended"
-
-    flipped_frontmatter = APPROVED_FRONTMATTER_PATTERN.sub(
-        "approved: true", frontmatter, count=1,
-    )
-    new_body = body.replace(frontmatter, flipped_frontmatter, 1)
-    new_body = new_body.rstrip("\n") + "\n" + audit_line + "\n"
-    p.write_text(new_body, encoding="utf-8")
-    return "frontmatter-flipped"
-
-
-def _apply_cli_implementation_option(path: str, option_name: str) -> str:
-    """`--implementation-option <name>` 이 지정된 경우 approved-plan frontmatter 의
-    `implementation-option:` 라인 값을 `option_name` 으로 치환한다.
-
-    동작 요약:
-      - frontmatter 의 `implementation-option:` 라인을
-        `implementation-option: <option_name>` 으로 교체 → `"frontmatter-set"`.
-      - audit 라인을 한 번 append (idempotent: 동일 audit 라인은 한 번만).
-      - frontmatter 가 없거나 `implementation-option:` 라인이 없으면 PrepareError
-        (report-writer 가 빈 값으로 이 라인을 항상 emit 하므로 라인은 존재해야 한다).
-
-    `--approve` (`_apply_cli_approval`) 의 frontmatter-치환 + audit-append 패턴을
-    그대로 미러한다.
-    """
-    p = Path(path)
-    if not p.is_file():
-        raise PrepareError(f"approved plan file not found: {path}")
-    body = p.read_text(encoding="utf-8", errors="replace")
-    frontmatter = _extract_frontmatter_block(body)
-    if frontmatter is None:
-        raise PrepareError(
-            f"--implementation-option was given but the approved-plan file has no YAML frontmatter: {path}\n"
-            "  expected the report to begin with `---\\n...\\n---\\n`."
-        )
-    if not IMPLEMENTATION_OPTION_FRONTMATTER_PATTERN.search(frontmatter):
+def _apply_cli_implementation_option(path: str, option_name: str) -> None:
+    """`--implementation-option <name>` 을 정본에 쓰고 열람본을 다시 렌더한다."""
+    p = _approved_plan_record(path)
+    loaded = _load_final_report_data_if_present(p)
+    if loaded is None:
+        raise PrepareError(f"approved plan data.json disappeared: {p}")
+    data_path, data = loaded
+    frontmatter = data.get("frontmatter")
+    if not isinstance(frontmatter, dict) or "implementationOption" not in frontmatter:
         raise PrepareError(
-            f"--implementation-option was given but the approved-plan frontmatter has no "
-            f"`implementation-option:` field: {path}\n"
-            "  expected a single line of the form `implementation-option:` "
-            "(report-writer worker emits this empty by default)."
+            f"--implementation-option was given but the approved-plan "
+            f"data.json has no frontmatter.implementationOption field: {data_path}"
         )
-
-    audit_iso = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-    audit_line = (
-        f"- 선택 옵션 (CLI): {audit_iso} — `{option_name}` recorded by "
-        "`okstra --implementation-option` (user-selected Option Candidate)"
-    )
-
-    # 렌더 경로(`final-report.template.md` 의 `yaml_scalar`)와 동일하게 값을
-    # YAML 따옴표 처리한다. 옵션명은 보통 `: `(콜론+공백)를 포함하므로 따옴표
-    # 없이 쓰면 frontmatter 가 invalid YAML 이 되고 CLI/렌더 출력이 어긋난다.
-    # 함수 치환을 써서 quoted 값 안의 백슬래시/그룹 참조가 re 치환 문법으로
-    # 재해석되는 것까지 막는다 (리터럴 치환).
-    from .render_final_report import _yaml_scalar
-
-    quoted = _yaml_scalar(option_name)
-    set_frontmatter = IMPLEMENTATION_OPTION_FRONTMATTER_PATTERN.sub(
-        lambda _m: f"implementation-option: {quoted}", frontmatter, count=1,
-    )
-    new_body = body.replace(frontmatter, set_frontmatter, 1)
-    if audit_line.split(" — ")[1] not in new_body:
-        new_body = new_body.rstrip("\n") + "\n" + audit_line + "\n"
-    p.write_text(new_body, encoding="utf-8")
-    return "frontmatter-set"
+    frontmatter["implementationOption"] = option_name
+    _commit_data_json_and_rerender(data_path, data, action="--implementation-option")
 
 
 def _ensure_task_directories(ctx: dict) -> None:
@@ -802,7 +700,7 @@ def _record_start(
             workers=[w for w in ctx.get("RECOMMENDED_ANALYSERS", "").split(",") if w],
             lead_model=ctx.get("LEAD_MODEL", ""),
             run_dir_rel=ctx.get("RUN_DIR_RELATIVE_PATH", ""),
-            final_report_rel=ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
+            final_report_record_rel=ctx.get("FINAL_REPORT_RECORD_RELATIVE_PATH", ""),
             final_status_rel=ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
             argv=canonical_argv,
             cwd=cwd,
@@ -1204,7 +1102,7 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
 
 
 _PLANNING_REPORT_RE = re.compile(
-    r"^final-report-implementation-planning-\d{3,}\.md$"
+    r"^final-report-implementation-planning-\d{3,}\.(?:md|data\.json)$"
 )
 
 
@@ -1343,37 +1241,11 @@ def _validate_reverify_scope(inp: PrepareInputs) -> None:
 def _implementation_plan_contract(
     inp: PrepareInputs,
 ) -> tuple[str, Path, dict | None]:
-    """Classify an implementation plan from its sibling data.json contract."""
-    plan_path = Path(inp.approved_plan_path)
-    body = plan_path.read_text(encoding="utf-8", errors="replace")
-    frontmatter = _extract_frontmatter_block(body) or ""
-    markdown_ref_match = SELECTED_DIRECTION_FRONTMATTER_PATTERN.search(frontmatter)
-    markdown_ref: str | None = None
-    if markdown_ref_match is not None:
-        markdown_ref = markdown_ref_match.group(1).strip()
-        if markdown_ref.startswith('"'):
-            try:
-                markdown_ref = json.loads(markdown_ref)
-            except json.JSONDecodeError as exc:
-                raise PrepareError(
-                    "selected-direction plan markdown `selected-direction-ref` is "
-                    "not a valid quoted string"
-                ) from exc
-        elif len(markdown_ref) >= 2 and markdown_ref[0] == markdown_ref[-1] == "'":
-            markdown_ref = markdown_ref[1:-1].replace("''", "'")
-        if not isinstance(markdown_ref, str) or not markdown_ref.strip():
-            raise PrepareError(
-                "selected-direction plan markdown `selected-direction-ref` must "
-                "be a non-empty string"
-            )
+    """Classify an implementation plan from its report record."""
+    plan_path = _approved_plan_record(inp.approved_plan_path)
     loaded = _load_final_report_data_if_present(plan_path)
     if loaded is None:
-        if markdown_ref_match is not None:
-            raise PrepareError(
-                "selected-direction plan requires its sibling data.json before "
-                f"implementation entry: {_final_report_data_path(plan_path)}"
-            )
-        return "legacy", plan_path, None
+        raise PrepareError(f"approved plan record could not be read: {plan_path}")
     _, data = loaded
     planning = data.get("implementationPlanning")
     if not isinstance(planning, dict):
@@ -1392,11 +1264,10 @@ def _implementation_plan_contract(
         )
     )
     if contract is None:
-        if markdown_ref_match is not None or selected_payload:
+        if selected_payload:
             raise PrepareError(
                 "selected-direction markers require "
-                "implementationPlanning.planningContract=`selected-direction`; "
-                "the markdown `selected-direction-ref` and data contract disagree"
+                "implementationPlanning.planningContract=`selected-direction`"
             )
         return "legacy", plan_path, data
     if contract != "selected-direction":
@@ -1404,27 +1275,6 @@ def _implementation_plan_contract(
             "approved plan sibling data.json has unsupported planningContract "
             f"{contract!r}"
         )
-    if markdown_ref_match is None:
-        raise PrepareError(
-            "selected-direction plan markdown frontmatter must contain "
-            "`selected-direction-ref:`"
-        )
-    selected_ref = planning.get("selectedDirectionRef")
-    snapshot_ref = (
-        selected_ref.get("snapshotPath")
-        if isinstance(selected_ref, dict)
-        else None
-    )
-    if not isinstance(markdown_ref, str) or markdown_ref != snapshot_ref:
-        raise PrepareError(
-            "selected-direction plan markdown `selected-direction-ref` must "
-            "exactly match implementationPlanning.selectedDirectionRef.snapshotPath"
-        )
-    if IMPLEMENTATION_OPTION_FRONTMATTER_PATTERN.search(frontmatter):
-        raise PrepareError(
-            "selected-direction plan must not contain an `implementation-option:` "
-            "frontmatter field"
-        )
     return "selected-direction", plan_path, data
 
 
@@ -3252,6 +3102,23 @@ def _write_prior_run_error_digest(ctx: dict, instruction_set: Path) -> None:
         (instruction_set / "prior-run-errors.md").write_text(digest, encoding="utf-8")
 
 
+def _stage_or_clear(path: Path, body: str) -> None:
+    """이 런의 값을 쓰거나, 값이 없으면 이전 런이 남긴 파일을 지운다.
+
+    instruction-set 은 run 단위가 아니라 **task 단위** 디렉터리다
+    (`paths.py`: `task_root / "instruction-set"`). 그래서 값이 있을 때만 쓰고
+    없을 때 아무것도 안 하면, 이전 런의 파일이 그대로 남아 다음 런의 입력이 된다.
+    directive 를 비우고 준비한 런에서 워커들이 예전 directive 를 읽고, 그 내용이
+    현재 기록과 어긋나 반박에 시간을 쓴 사례가 보고됐다. carry-in 답변
+    (`clarification-response.md`)은 같은 형태에 결과가 더 나쁘다 — 남은 파일이
+    analysis packet 에 그대로 실린다.
+    """
+    if body:
+        path.write_text(body, encoding="utf-8")
+        return
+    path.unlink(missing_ok=True)
+
+
 def _write_instruction_set_sources(
     inp: PrepareInputs,
     ctx: dict,
@@ -3328,22 +3195,26 @@ def _write_instruction_set_sources(
         )
     ctx["HOST_ORCHESTRATION_RULES_RELATIVE_PATH"] = host_rules_relative
     if inp.clarification_response_path:
-        (instruction_set / "clarification-response.md").write_text(
-            clarification_response_with_sidecars(Path(inp.clarification_response_path)),
-            encoding="utf-8",
+        clarification_body = clarification_response_with_sidecars(
+            Path(inp.clarification_response_path)
         )
     elif inp.task_type == "implementation" and inp.approved_plan_path:
         # implementation carry-in: the approved plan reaches this run by path
         # (executor re-reads it), so attach ONLY the planning HTML form answers
         # (`runs/implementation-planning/.../user-responses/`) — without these
         # the user's clarification answers never reach the implementation run.
-        plan_responses = attached_user_responses_section(Path(inp.approved_plan_path))
-        if plan_responses:
-            (instruction_set / "clarification-response.md").write_text(
-                plan_responses, encoding="utf-8",
-            )
-    if inp.directive:
-        (instruction_set / "directive.txt").write_text(inp.directive + "\n", encoding="utf-8")
+        clarification_body = attached_user_responses_section(
+            Path(inp.approved_plan_path)
+        )
+    else:
+        clarification_body = ""
+    _stage_or_clear(
+        instruction_set / "clarification-response.md", clarification_body
+    )
+    _stage_or_clear(
+        instruction_set / "directive.txt",
+        inp.directive + "\n" if inp.directive else "",
+    )
     render_reference_expectations(
         str(inp.brief_path), str(instruction_set / "reference-expectations.md"), ctx,
     )
@@ -3361,6 +3232,11 @@ def _write_instruction_set_sources(
         instruction_set_relative_path=ctx["INSTRUCTION_SET_RELATIVE_PATH"],
         fix_history_text=fix_cycles.packet_summary(
             fix_cycles.read_rows(Path(ctx["TASK_MANIFEST_PATH"]).parent)),
+        stage_ledger_json=(
+            render_stage_ledger(
+                build_stage_ledger(Path(ctx["TASK_MANIFEST_PATH"]).parent))
+            if inp.task_type == "implementation-planning" else ""
+        ),
     )
     if inp.task_type in ANALYSIS_TASK_TYPES:
         packet += (
@@ -3620,7 +3496,7 @@ def _maybe_open_fix_cycle(inp: PrepareInputs, task_root: Path, existing: dict,
             "(workflow.lastCompletedPhase 확인)")
     brief_text = Path(inp.brief_path).read_text(encoding="utf-8")
     fix_cycles.append_opened(
-        task_root, target_report=str(existing.get("latestReportPath", "")),
+        task_root, target_report=str(existing.get("latestReportRecordPath", "")),
         symptom=fix_cycles.derive_symptom(brief_text), opened_at=now)
     return fix_cycles.open_cycle(fix_cycles.read_rows(task_root))
 
@@ -3650,7 +3526,7 @@ def _record_fix_cycle_events(inp: PrepareInputs, ctx: dict) -> str:
         if handoff_attached:
             fix_cycles.append_closed(
                 task_root, cycle=open_c["cycle"], closed_by="release-handoff",
-                report=str(existing.get("latestReportPath", "")), closed_at=now)
+                report=str(existing.get("latestReportRecordPath", "")), closed_at=now)
             open_c = None
 
     if inp.fix_cycle == "yes" and open_c is None:
@@ -3680,7 +3556,7 @@ def _finalize_status_and_render_manifests(
         ctx["CURRENT_TASK_STATUS"] = "lead-session-started"
         ctx["CURRENT_RUN_STATUS"] = "in-progress"
     ctx["LATEST_REPORT_PATH"] = ctx["FINAL_REPORT_PATH"]
-    ctx["LATEST_REPORT_RELATIVE_PATH"] = ctx["FINAL_REPORT_RELATIVE_PATH"]
+    ctx["LATEST_REPORT_RECORD_RELATIVE_PATH"] = ctx["FINAL_REPORT_RECORD_RELATIVE_PATH"]
     ctx.update(compute_workflow_state(
         task_type=inp.task_type,
         current_run_status=ctx["CURRENT_RUN_STATUS"],
@@ -4330,7 +4206,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "VALIDATION_UPDATED_AT": "",
         "VALIDATION_FAILURES_JSON": "[]",
         "LATEST_REPORT_PATH": "",
-        "LATEST_REPORT_RELATIVE_PATH": "",
+        "LATEST_REPORT_RECORD_RELATIVE_PATH": "",
         "RENDER_ONLY": "true" if inp.render_only else "false",
         "OKSTRA_VERSION": installed_version(),
         "EXECUTION_IDENTITY_JSON": json.dumps(
@@ -4516,8 +4392,8 @@ def build_prepare_argument_parser():
         dest="approve_plan_ack",
         help=(
             "Treat the CLI invocation itself as the plan approval signal. "
-            "Flips `approved: false` to `approved: true` in the --approved-plan file's "
-            "YAML frontmatter and appends an audit line."
+            "Sets the report record `frontmatter.approved` to true and refreshes "
+            "the full reading copy."
         ),
     )
     p.add_argument(
@@ -4527,8 +4403,8 @@ def build_prepare_argument_parser():
         help=(
             "implementation task only. Name of the Option Candidate the user "
             "chose from the implementation-planning final-report. Written into "
-            "the --approved-plan file's `implementation-option:` frontmatter "
-            "line. When omitted, implementation falls back to the plan's "
+            "the report record `frontmatter.implementationOption` (schema-v1: "
+            "the markdown `implementation-option:` line). When omitted, implementation falls back to the plan's "
             "`Recommended Option`."
         ),
     )