okstra 0.188.0 → 0.189.0

package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py

@@ -32,13 +32,25 @@ from ...assignment_resolver import AssignmentContext, resolve_dispatch_assignmen
 from ...path_hints import hydrate_active_run_context
 from ...worker_prompt_headers import worker_prompt_headers
 from ...final_report_paths import final_report_data_path
+from ...final_report_schema import load_schema_version
 from ...report_inputs import report_narrative_path, uses_report_contract_v3
+from ...report_narrative import NarrativeContractError, parse_narrative_structure
 from ...report_synthesis_packet import (
     ReportSynthesisPacketError,
     materialize_report_synthesis_packet,
 )
 from ...worker_prompt_body import report_writer_input_lines
 from ...dispatch_state import detect_terminal_backend
+from ...report_corrections import (
+    body_owned_section_conflicts,
+    render_corrections_section,
+    render_output_section,
+)
+from .corrections import (
+    corrections_payload,
+    run_corrections_apply,
+    run_corrections_check,
+)
 from .dynamic_verifier import (
     _dynamic_verifier_source,
     _reserve_dynamic_verifier_request,
@@ -270,6 +282,26 @@ def _materialize_run(
                 narrative_path=result_path,
             ),
         )
+    if args.audience == "report-writer" and uses_report_contract_v3(manifest):
+        body = _with_report_writer_sections(
+            args,
+            project_root,
+            manifest,
+            authorized,
+            active_context,
+            body,
+            narrative_path=result_path,
+        )
+    elif getattr(args, "corrections", None):
+        if args.audience != "report-writer":
+            raise AgentPromptCliError(
+                "--corrections is a report-writer materialization option; "
+                f"audience {args.audience} has no corrections ledger"
+            )
+        raise AgentPromptCliError(
+            "--corrections requires report contract 3.0 (a Markdown narrative); "
+            "this run uses an older contract"
+        )
     request = AgentInvocationRequest(
         invocation_id=args.invocation_id,
         worker_id=args.worker_id if identity is None else None,
@@ -315,6 +347,165 @@ def _normalized(path: Path) -> Path:
     return Path(os.path.normpath(path))
 
 
+def _with_report_writer_sections(
+    args: argparse.Namespace,
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    authorized: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    body: str,
+    *,
+    narrative_path: Path,
+) -> str:
+    """run 갈래 report-writer 프롬프트의 okstra 소유 절을 본문 끝에 렌더한다.
+
+    `## Output` 은 매 디스패치에 렌더한다 — 세 산출물을 리드가 손으로 열거하다
+    하나를 빠뜨리면 `required worker artifact was not produced` 로 끝났다.
+    `--corrections` 가 있으면 원장을 대조해 `## Corrections` 를 그 앞에 둔다.
+    리드가 자유 서술로 적던 교정 지시는 기계가 대조할 수 없어 값 오류가
+    조립에서야 드러났다(2026-09-03 실측: 재실행 6회 중 4회). 그래서 원장 없는
+    교정 디스패치(서사가 이미 있고 파싱되는 경우)는 거절한다. 두 절은 okstra 가
+    렌더하므로 본문에 같은 제목이 있으면 거절한다.
+    """
+    conflicts = body_owned_section_conflicts(body)
+    if conflicts:
+        raise AgentPromptCliError(
+            f"instruction body must not contain {', '.join(conflicts)}: okstra "
+            "renders those sections itself (## Output from the run manifest, "
+            "## Corrections from the --corrections ledger)"
+        )
+    sections: list[str] = []
+    if getattr(args, "corrections", None):
+        corrections_path = _authorized_path(
+            project_root,
+            args.corrections,
+            authorized.get("instructionRoots"),
+            "corrections",
+            must_exist=True,
+        )
+        check = run_corrections_check(
+            project_root=project_root,
+            manifest=manifest,
+            active_context=active_context,
+            team_state=_load_team_state(project_root, manifest),
+            corrections_path=corrections_path,
+            narrative_path=narrative_path,
+        )
+        if check.defects:
+            raise AgentPromptCliError(
+                "report-writer corrections defects: " + "; ".join(check.defects)
+            )
+        sections.extend(render_corrections_section(
+            check,
+            base_narrative_rel=str(check.ledger.get("baseNarrativePath") or ""),
+            corrections_rel=_relative(project_root, corrections_path),
+        ))
+        sections.append("")
+    else:
+        _refuse_free_form_correction(project_root, narrative_path)
+    sections.extend(render_output_section())
+    return body.rstrip("\n") + "\n\n" + "\n".join(sections) + "\n"
+
+
+def _refuse_free_form_correction(project_root: Path, narrative_path: Path) -> None:
+    """서사가 이미 있고 구조가 읽히면 이 디스패치는 교정이다 — 원장 없이는 거절한다.
+
+    구조가 읽히지 않는 서사(줄 문법·소유권 결함)는 교정 대상이 아니라 재저작
+    대상이다(원장의 경로가 해소될 자료가 없다). 그 디스패치는 원장 없이
+    통과한다. 값 결함(패턴 밖 id, enum 밖 값)은 구조가 읽히는 서사이고, 그것이
+    원장이 고치는 자리다 — 실측(dev-10626 a3)의 `SC-` id 20곳이 이 경우다.
+    """
+    if not narrative_path.is_file():
+        return
+    try:
+        parse_narrative_structure(
+            narrative_path.read_text(encoding="utf-8"), load_schema_version("3.0"),
+        )
+    except NarrativeContractError:
+        return
+    narrative_rel = _relative(project_root, narrative_path)
+    raise AgentPromptCliError(
+        f"report-writer narrative already exists at {narrative_rel} and parses, "
+        "so this is a corrective dispatch, and a free-form correction is refused: "
+        "nothing can check it before the writer runs. Write a corrections ledger "
+        "(schemas/report-writer-corrections-v1.0.schema.json; baseNarrativePath "
+        "names a preserved copy of that attempt), run `okstra agent-prompt "
+        "check-corrections --project-root <root> --run-manifest <manifest> "
+        "--corrections <ledger>` until it reports no defect, then pass the same "
+        "--corrections here. A ledger of only replace/remove entries needs no "
+        "writer round: `okstra agent-prompt apply-corrections` writes the "
+        "narrative and records the activity row. Only a narrative whose "
+        "structure does not parse (line grammar, unknown top-level field) is "
+        "re-authored without a ledger; value defects are what the ledger fixes"
+    )
+
+
+def _corrections_context(
+    args: argparse.Namespace,
+) -> tuple[Path, Path, dict[str, Any], Mapping[str, Any], Path]:
+    """`check-corrections`·`apply-corrections` 가 공유하는 입력 해소."""
+    project_root = _project_root(args.project_root)
+    manifest_path = _project_input(project_root, args.run_manifest, "run manifest")
+    manifest = _read_json_object(manifest_path, "run manifest")
+    contract = _mapping(manifest.get("agentContract"), "run agent contract")
+    authorized = _mapping(contract.get("authorizedPaths"), "authorized paths")
+    corrections_path = _authorized_path(
+        project_root,
+        args.corrections,
+        authorized.get("instructionRoots"),
+        "corrections",
+        must_exist=True,
+    )
+    active_context_path = _project_manifest_path(
+        project_root,
+        manifest.get("activeRunContextPath"),
+        "active run context",
+        must_exist=True,
+    )
+    active_context = hydrate_active_run_context(
+        _read_json_object(active_context_path, "active run context")
+    )
+    return project_root, manifest_path, manifest, active_context, corrections_path
+
+
+def _check_corrections(args: argparse.Namespace) -> dict[str, Any]:
+    """`okstra agent-prompt check-corrections` — 실체화 없이 원장만 대조한다."""
+    project_root, _manifest_path, manifest, active_context, corrections_path = (
+        _corrections_context(args)
+    )
+    narrative_path = (
+        report_narrative_path(project_root, manifest)
+        if uses_report_contract_v3(manifest)
+        else project_root
+    )
+    check = run_corrections_check(
+        project_root=project_root,
+        manifest=manifest,
+        active_context=active_context,
+        team_state=_load_team_state(project_root, manifest),
+        corrections_path=corrections_path,
+        narrative_path=narrative_path,
+    )
+    return corrections_payload(
+        check, project_root=project_root, corrections_path=corrections_path,
+    )
+
+
+def _apply_corrections(args: argparse.Namespace) -> dict[str, Any]:
+    """`okstra agent-prompt apply-corrections` — 기계적 원장을 서사에 쓴다."""
+    project_root, manifest_path, manifest, active_context, corrections_path = (
+        _corrections_context(args)
+    )
+    return run_corrections_apply(
+        project_root=project_root,
+        manifest=manifest,
+        manifest_path=manifest_path,
+        active_context=active_context,
+        team_state=_load_team_state(project_root, manifest),
+        corrections_path=corrections_path,
+    )
+
+
 def _validate_report_writer_paths(
     project_root: Path,
     manifest: Mapping[str, Any],

package/runtime/python/okstra_ctl/report_corrections.py

@@ -0,0 +1,443 @@
+"""report-writer 교정 원장 — 리드의 교정 요청을 기계가 대조하는 형태로 받는다.
+
+리드가 report-writer 에게 보내던 교정 지시는 자유 서술 Markdown 이라, 필드
+경로·현재값·대체값을 정확히 적으라는 계약이 있어도 기계가 대조할 수 없었다.
+실측(2026-09-03, dev-10626 implementation-option-selection): 재실행 6회 중 4회가
+리드 지시문이 저작 계약과 반대인 경우였고, 오류는 report assembly 에서야
+드러났다. 이 모듈은 그 지시를 원장(`report-writer-corrections-*.json`)으로
+받아 이전 서사에 적용해 보고, 스키마·task 의미 검증기로 대조해 결함 전건을
+한 번에 낸다. 설계: `.project-docs/specs/2026-09-03-report-writer-structured-corrections-design.md`.
+
+경로 문법은 검증기 메시지의 것과 같다 — 스키마 키를 `.` 로 잇고 배열 항목은
+0 기반 `[i]` 다. 조립 거절 메시지의 경로를 그대로 복사해 원장에 넣을 수 있다.
+"""
+from __future__ import annotations
+
+import json
+import re
+from copy import deepcopy
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Mapping, Sequence
+
+from .final_report_schema import validate
+from .json_boundary import JsonBoundaryError, load_owned_object
+from .report_markdown import humanise
+from .report_narrative import (
+    NarrativeContractError,
+    parse_narrative_structure,
+    render_narrative,
+    validate_writer_owned,
+    writer_owned_path_defect,
+)
+
+
+CORRECTION_KINDS = ("replace", "remove", "rewrite")
+MECHANICAL_KINDS = frozenset({"replace", "remove"})
+# okstra 가 렌더하는 절. 지시문 본문에 있으면 두 절이 갈라지므로 거절한다.
+OKSTRA_OWNED_SECTIONS = ("## Corrections", "## Output")
+
+_SCHEMA_RELATIVE = ("schemas", "report-writer-corrections-v1.0.schema.json")
+_SEGMENT_RE = re.compile(r"^([A-Za-z][A-Za-z0-9]*)((?:\[\d+\])*)$")
+_INDEX_RE = re.compile(r"\[(\d+)\]")
+
+
+class ReportCorrectionsError(ValueError):
+    """교정 원장을 적용할 수 없다 — 결함 전건이 메시지에 실린다."""
+
+    def __init__(self, defects: Sequence[str]) -> None:
+        self.defects = tuple(defects)
+        super().__init__("; ".join(self.defects))
+
+
+@dataclass(frozen=True)
+class CorrectionsCheck:
+    """원장 대조 결과. `defects` 가 비어야 디스패치할 수 있다."""
+
+    ledger: dict[str, Any]
+    corrections: tuple[dict[str, Any], ...]
+    # 기계적 교정(replace·remove)을 적용한 서사 자료. 기준 서사를 못 읽었으면 None.
+    scratch: dict[str, Any] | None
+    # 작성자 라운드 없이 끝나는가 — rewrite 가 없고 결함도 없다.
+    mechanical: bool
+    # rewrite 교정 id → 그 경로의 스키마 제약 문장(`task_block_rules` 줄).
+    constraints: dict[str, tuple[str, ...]]
+    defects: tuple[str, ...]
+
+    @property
+    def ok(self) -> bool:
+        return not self.defects
+
+
+def _defect(correction_id: str, path: str, reason: str) -> str:
+    return f"owner=lead correction={correction_id} path={path} reason={reason}"
+
+
+def _schema_path() -> Path:
+    from .paths import find_asset_root
+
+    root = find_asset_root(_SCHEMA_RELATIVE)
+    if root is None:
+        raise ReportCorrectionsError([
+            _defect("ledger", "-", "could not locate report-writer-corrections-v1.0.schema.json; "
+                    "set OKSTRA_HOME or run from a checkout that contains schemas/")
+        ])
+    return root.joinpath(*_SCHEMA_RELATIVE)
+
+
+def corrections_schema() -> dict[str, Any]:
+    return load_owned_object(_schema_path(), artifact="report-writer corrections schema")
+
+
+def load_corrections(path: Path) -> tuple[dict[str, Any], list[str]]:
+    """원장을 읽고 스키마 결함을 전건 모은다. 읽기 실패도 결함 한 건이다."""
+    try:
+        payload = load_owned_object(path, artifact="report-writer corrections")
+    except (OSError, JsonBoundaryError) as exc:
+        return {}, [_defect("ledger", str(path), f"corrections ledger is unreadable: {exc}")]
+    defects = [
+        _defect("ledger", error.split(": ", 1)[0], error)
+        for error in validate(payload, corrections_schema())
+    ]
+    return payload, defects
+
+
+def parse_field_path(path: str) -> tuple[str | int, ...]:
+    """`a.b[1].c` → ("a", "b", 1, "c"). 문법 밖이면 ValueError."""
+    tokens: list[str | int] = []
+    if not isinstance(path, str) or not path.strip():
+        raise ValueError("field path is empty")
+    for segment in path.split("."):
+        match = _SEGMENT_RE.match(segment)
+        if match is None:
+            raise ValueError(
+                f"field path segment `{segment}` is not `<key>` or `<key>[<index>]`"
+            )
+        tokens.append(match.group(1))
+        tokens.extend(int(index) for index in _INDEX_RE.findall(match.group(2)))
+    return tuple(tokens)
+
+
+def normalise_field_path(path: str) -> str:
+    """`a.b[1].c` → `a.b[].c` — `task_block_rules` 가 쓰는 경로 표기."""
+    return _INDEX_RE.sub("[]", path)
+
+
+def humanise_field_path(tokens: Sequence[str | int]) -> str:
+    """스키마 키 경로를 작성자가 쓰는 라벨 경로로: `Ranked Options` -> `Item 2`."""
+    parts = [
+        f"`Item {token + 1}`" if isinstance(token, int) else f"`{humanise(token)}`"
+        for token in tokens
+    ]
+    return " -> ".join(parts)
+
+
+def _resolve(data: Any, tokens: Sequence[str | int]) -> tuple[bool, Any]:
+    node = data
+    for token in tokens:
+        if isinstance(token, int):
+            if not isinstance(node, list) or not 0 <= token < len(node):
+                return False, None
+            node = node[token]
+        else:
+            if not isinstance(node, dict) or token not in node:
+                return False, None
+            node = node[token]
+    return True, node
+
+
+def _parent(data: Any, tokens: Sequence[str | int]) -> tuple[bool, Any]:
+    return _resolve(data, tokens[:-1]) if tokens else (False, None)
+
+
+def _set(data: Any, tokens: Sequence[str | int], value: Any) -> None:
+    found, parent = _parent(data, tokens)
+    if not found:
+        raise KeyError(tokens)
+    last = tokens[-1]
+    if isinstance(last, int):
+        parent[last] = value
+    else:
+        parent[last] = value
+
+
+def _remove(data: Any, tokens: Sequence[str | int]) -> None:
+    found, parent = _parent(data, tokens)
+    if not found:
+        raise KeyError(tokens)
+    last = tokens[-1]
+    if isinstance(last, int):
+        del parent[last]
+    else:
+        del parent[last]
+
+
+def _removal_order(token: str | int) -> tuple[int, Any]:
+    # 같은 배열의 항목은 뒤 번호부터 지워야 앞 번호가 밀리지 않는다.
+    return (0, token) if isinstance(token, int) else (1, token)
+
+
+def _current_matches(expected: Any, actual: Any) -> bool:
+    return json.dumps(expected, sort_keys=True) == json.dumps(actual, sort_keys=True)
+
+
+def _short(value: Any) -> str:
+    text = json.dumps(value, ensure_ascii=False)
+    return text if len(text) <= 120 else text[:117] + "..."
+
+
+def check_corrections(
+    *,
+    ledger: Mapping[str, Any],
+    base_narrative: str,
+    schema: Mapping[str, Any],
+    block_rules: Sequence[str] = (),
+    semantic_validator: Callable[[dict[str, Any]], Sequence[str]] | None = None,
+) -> CorrectionsCheck:
+    """원장을 기준 서사에 대조한다. 설계 §4.2 의 1~6단계.
+
+    1. 원장 스키마, id·경로 중복, 경로 문법.
+    2. 기준 서사 파싱 — 구조만 읽는다(`parse_narrative_structure`). 줄 문법이나
+       소유권 결함이면 그 결함만 내고 멈춘다(적용할 자료가 없다). 기준 서사의
+       값 결함은 원장이 고칠 자리이므로 여기서는 결함이 아니고, 5단계에서
+       적용 뒤에도 남아 있는 것만 보고한다.
+    3. 경로 해소와 `current` 일치. `rewrite` 는 배열의 `[len]` 추가 위치를 허용한다.
+    4. 작성자 소유 경로인가.
+    5. replace·remove 를 적용한 사본을 작성자 소유 값 스키마와 task 의미 검증기로
+       대조한다. rewrite 경로 아래의 스키마 결함은 뺀다(작성자가 다시 쓸 자리다).
+    6. rewrite 마다 그 경로의 스키마 제약 문장을 붙인다.
+    """
+    ledger_dict = dict(ledger)
+    defects: list[str] = [
+        _defect("ledger", error.split(": ", 1)[0], error)
+        for error in validate(ledger_dict, corrections_schema())
+    ]
+    raw_corrections = ledger_dict.get("corrections")
+    corrections = tuple(
+        dict(item) for item in (raw_corrections if isinstance(raw_corrections, list) else [])
+        if isinstance(item, Mapping)
+    )
+    ids = [str(item.get("id")) for item in corrections]
+    for duplicate in sorted({value for value in ids if ids.count(value) > 1}):
+        defects.append(_defect(duplicate, "-", "correction id is not unique"))
+    paths = [str(item.get("path")) for item in corrections]
+    for duplicate in sorted({value for value in paths if paths.count(value) > 1}):
+        defects.append(_defect("-", duplicate, "two corrections name the same path"))
+    parsed: dict[str, tuple[str | int, ...]] = {}
+    for item in corrections:
+        correction_id, path = str(item.get("id")), str(item.get("path"))
+        try:
+            parsed[correction_id] = parse_field_path(path)
+        except ValueError as exc:
+            defects.append(_defect(correction_id, path, str(exc)))
+    if defects and not parsed:
+        return CorrectionsCheck(ledger_dict, corrections, None, False, {}, tuple(defects))
+
+    try:
+        data, _base_defects = parse_narrative_structure(base_narrative, schema)
+    except NarrativeContractError as exc:
+        defects.append(_defect(
+            "ledger", str(ledger_dict.get("baseNarrativePath") or "-"),
+            f"base narrative does not parse: {exc}",
+        ))
+        return CorrectionsCheck(ledger_dict, corrections, None, False, {}, tuple(defects))
+
+    scratch = deepcopy(data)
+    rewrite_paths: list[str] = []
+    constraints: dict[str, tuple[str, ...]] = {}
+    for item in corrections:
+        correction_id, path, kind = str(item.get("id")), str(item.get("path")), str(item.get("kind"))
+        tokens = parsed.get(correction_id)
+        if tokens is None:
+            continue
+        owned_defect = writer_owned_path_defect(path)
+        if owned_defect:
+            defects.append(_defect(correction_id, path, owned_defect))
+            continue
+        found, value = _resolve(data, tokens)
+        if not found:
+            parent_found, parent = _parent(data, tokens)
+            appendable = (
+                kind == "rewrite"
+                and isinstance(tokens[-1], int)
+                and parent_found
+                and isinstance(parent, list)
+                and tokens[-1] == len(parent)
+            )
+            if not appendable:
+                defects.append(_defect(
+                    correction_id, path,
+                    "path does not resolve in the base narrative"
+                    + (" (a rewrite may append at index len(array))" if kind == "rewrite" else ""),
+                ))
+                continue
+        elif "current" in item and not _current_matches(item["current"], value):
+            defects.append(_defect(
+                correction_id, path,
+                f"current value is {_short(value)}, not {_short(item['current'])}",
+            ))
+            continue
+        if kind == "rewrite":
+            rewrite_paths.append(path)
+            constraints[correction_id] = _constraints_for(path, block_rules)
+
+    replacements = [c for c in corrections if c.get("kind") == "replace" and str(c.get("id")) in parsed]
+    removals = [c for c in corrections if c.get("kind") == "remove" and str(c.get("id")) in parsed]
+    defective_ids = {
+        line.split("correction=", 1)[1].split(" ", 1)[0] for line in defects if "correction=" in line
+    }
+    for item in replacements:
+        correction_id = str(item.get("id"))
+        if correction_id in defective_ids:
+            continue
+        _set(scratch, parsed[correction_id], deepcopy(item.get("replacement")))
+    for item in sorted(
+        removals,
+        key=lambda c: tuple(_removal_order(t) for t in parsed[str(c.get("id"))]),
+        reverse=True,
+    ):
+        correction_id = str(item.get("id"))
+        if correction_id in defective_ids:
+            continue
+        _remove(scratch, parsed[correction_id])
+
+    # 원장의 일부가 결함이어도 나머지를 적용한 사본은 검증한다 — 리드가 한
+    # 회차에 전건을 보게 하려는 것이 이 모듈의 이유다. 결함인 교정은 적용하지
+    # 않았으므로 그 자리는 기준 서사의 값 그대로다.
+    if scratch is not None:
+        for error in validate_writer_owned(scratch, schema):
+            location = error.split(": ", 1)[0]
+            if any(location == rp or location.startswith(f"{rp}.") or location.startswith(f"{rp}[")
+                   for rp in rewrite_paths):
+                continue
+            defects.append(_defect("applied", location, error))
+        if semantic_validator is not None:
+            for error in semantic_validator(scratch):
+                defects.append(_defect("applied", "-", str(error)))
+
+    mechanical = not defects and not rewrite_paths
+    return CorrectionsCheck(
+        ledger_dict, corrections, scratch, mechanical, constraints, tuple(defects)
+    )
+
+
+def _constraints_for(path: str, block_rules: Sequence[str]) -> tuple[str, ...]:
+    """이 경로(또는 가장 가까운 상위 객체)의 `task_block_rules` 줄."""
+    normalised = normalise_field_path(path)
+    candidates = [normalised]
+    while "." in candidates[-1]:
+        candidates.append(candidates[-1].rsplit(".", 1)[0])
+    for candidate in candidates:
+        lines = tuple(
+            rule for rule in block_rules
+            if rule.startswith(f"`{candidate}`: ")
+        )
+        if lines:
+            return lines
+    return ()
+
+
+def render_applied_narrative(
+    check: CorrectionsCheck, schema: Mapping[str, Any],
+) -> str:
+    """기계적 교정(replace·remove)만 있는 원장을 적용한 서사 본문.
+
+    작성자 라운드 없이 okstra 가 `reportNarrativePath` 에 쓰는 문서다. 결함이
+    있거나 `rewrite` 가 섞인 대조 결과는 받지 않는다 — 그 원장은 작성자가 다시
+    써야 할 자리가 있다.
+    """
+    if not check.mechanical or check.scratch is None:
+        pending = [
+            str(item.get("id")) for item in check.corrections
+            if item.get("kind") == "rewrite"
+        ]
+        raise ReportCorrectionsError(
+            list(check.defects)
+            or [_defect(
+                ", ".join(pending) or "-", "-",
+                "rewrite entries need a writer round; only a ledger of replace "
+                "and remove entries can be applied mechanically",
+            )]
+        )
+    return render_narrative(check.scratch, schema)
+
+
+def body_owned_section_conflicts(body: str) -> list[str]:
+    """지시문 본문이 okstra 소유 절의 제목을 쓰면 그 제목들."""
+    present = {line.strip() for line in body.splitlines()}
+    return [section for section in OKSTRA_OWNED_SECTIONS if section in present]
+
+
+def _scalar_text(value: Any) -> str:
+    if isinstance(value, str):
+        if "\n" in value:
+            lines = value.split("\n")
+            return "the following lines, one `> ` line each: " + " / ".join(f"`{line}`" for line in lines)
+        return f"`{value}`"
+    if value is None:
+        return "`_none_`"
+    if isinstance(value, bool):
+        return f"`{str(value).lower()}`"
+    if isinstance(value, (int, float)):
+        return f"`{value}`"
+    return "this JSON value rendered in narrative form: `" + json.dumps(value, ensure_ascii=False) + "`"
+
+
+def render_corrections_section(
+    check: CorrectionsCheck, *, base_narrative_rel: str, corrections_rel: str,
+) -> list[str]:
+    """프롬프트의 `## Corrections` 절. 검증을 통과한 원장만 렌더한다."""
+    lines = [
+        "## Corrections",
+        "",
+        f"Your previous attempt is preserved at `{base_narrative_rel}`. Read that copy "
+        "and reproduce it verbatim, then apply only the corrections below. Do not read "
+        "your own `**Result Path:**` for this purpose: it is the same document and you "
+        f"are about to overwrite it. Corrections ledger: `{corrections_rel}`.",
+        "",
+    ]
+    for item in check.corrections:
+        correction_id = str(item.get("id"))
+        path = str(item.get("path"))
+        kind = str(item.get("kind"))
+        try:
+            label = humanise_field_path(parse_field_path(path))
+        except ValueError:
+            label = f"`{path}`"
+        head = f"- {correction_id} `{kind}` — {label} (`{path}`): "
+        if kind == "replace":
+            current = (
+                f"current {_scalar_text(item['current'])}, " if "current" in item else ""
+            )
+            action = f"{current}write exactly {_scalar_text(item.get('replacement'))}."
+        elif kind == "remove":
+            action = "remove this item or field entirely; renumber the remaining `- Item N` rows 1..N."
+        else:
+            action = f"rewrite this part so that: {item.get('rule')}"
+        constraint_lines = check.constraints.get(correction_id, ())
+        if constraint_lines:
+            action += " Schema constraint: " + " ".join(constraint_lines)
+        lines.append(f"{head}{action} Reason: {item.get('reason')}")
+    context = check.ledger.get("context")
+    if isinstance(context, str) and context.strip():
+        lines.extend(["", "### Context", "", context.strip()])
+    lines.extend([
+        "",
+        "Change nothing else: not a sentence, not a score, not an evidence path, not a "
+        "verdict, not the `Human Summary`, and not the blockquote indentation where each "
+        "value line sits two spaces deeper than its own `- **Label**` line.",
+    ])
+    return lines
+
+
+def render_output_section() -> list[str]:
+    """프롬프트의 `## Output` 절 — 세 산출물을 okstra 가 열거한다."""
+    return [
+        "## Output",
+        "",
+        "Write all three artifacts before returning.",
+        "",
+        "1. The report narrative Markdown at `**Result Path:**`.",
+        "2. The pointer record at `**Worker Result Path:**`.",
+        "3. The reading audit at `**Audit sidecar path:**`.",
+    ]