okstra 0.200.1 → 0.201.1

package/runtime/prompts/profiles/implementation-option-selection.md

@@ -49,7 +49,7 @@ roles:
   - Map every displayed candidate or preselected direction to the stable brief end-state IDs it satisfies, preserves, or leaves unresolved.
   - **Close the vote gaps before you conclude `blocked`.** Round 1 runs the designers in parallel, so each one votes only on the candidates it proposed and the merged set ends up with a different hole per analyser. A candidate that is otherwise sound then fails the every-analyser clause and drops out of the ranking — three such candidates blocked a run whose comparison had in fact converged (2026-09-10, dev-10629-4: IO-001, IO-002 and IO-003 each held two `feasible` votes and each was missing a different designer). Run `okstra option-votes gaps --task-manifest <taskManifestPath> --narrative <report writer narrative>` before assembly. For each analyser it names, dispatch one vote-completion assignment asking for that analyser's own feasibility verdict, rationale, and counterevidence on the named candidate — no new candidate, so the run stays in `candidate-comparison` mode. The command reports no gap when a vote cannot settle the block (safety blockers, unresolved feasibility facts, too few feasible verdicts); that is the honest `blocked`.
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
-  - **A blocked run must leave an answer channel.** `routing: blocked` is this phase's only end state with no destination, and its usual cause is `unresolvedFeasibilityFacts` — an undecided value, a missing payload contract, an unconfirmed reporter intent. Those are the user's to settle, and the only channel that reaches them is `clarificationItems[]`. Before assembly, open one `Kind=decision, Blocks=next-phase` row per answerable fact. A fact left in `humanSummary.blockers`, `selectionGuidance`, or a follow-up task reaches no answer channel: `okstra user-response` shows the user zero questions on a run that is waiting for their answer. **Enforced:** `scripts/okstra_ctl/implementation_options.py` `validate_blocked_answer_channel` fails a `blocked` report whose candidates carry unresolved facts while no clarification row is open. A block with no unresolved facts — every analyser's result missing, for instance — has nothing for the user to answer and is exempt.
+  - Classify every `unresolvedFeasibilityFacts` entry with `resolutionKind`: `user-decision` requires nonempty `clarificationRefs` naming the actual C-NNN records for that fact; `technical-verification` requires source review, design evidence, or experiments and does not require a user question. Preserve `fact`, `whyItMatters`, and `evidence`. Reuse answered questions and their recorded dispositions; never reopen one merely to save the report. An unrelated open question does not satisfy a missing reference. Historical unclassified entries remain readable, but blocked report reassembly requires the writer to classify them explicitly. Enforced by `validate_blocked_answer_channel` in `scripts/okstra_ctl/implementation_options.py`, called by report assembly and `validate-run.py`. Saving preserves `routing: blocked` and does not make a candidate valid. In `humanSummary.actions`, `verdictCard.nextStep`, and selection guidance, distinguish pending user decisions from remaining technical verification; after the pilot route is answered, carry the selected route and remove the old answer-waiting instruction.
 {{INCLUDE:_clarification-recommendation.md}}
 - Cross-verification mode:
   - Phase 5.5 convergence runs in adversarial mode (`convergence.adversarial=true`).
@@ -57,3 +57,9 @@ roles:
   - source or configuration edits, tests, builds, migrations, deployments, or other state-mutating commands
   - detailed implementation planning, file-change specifications, stage maps, execution commands, or user approval
   - starting `implementation-planning` or any other lifecycle phase inside this run
+
+## Technical evidence loop
+
+When no candidate is valid and explicit eligible technical facts remain, route to `technical-verification` to collect experimental evidence. Keep `rankedOptions` empty and `recommendedOptionId` null. `validate_blocked_answer_channel` rejects this route while user decisions remain unresolved or no safe, explicitly classified technical fact is available. Historical blocked reports can be supplied explicitly without rewriting their verdict.
+
+When `--clarification-response` carries a technical-verification report, read its source comparison, experiment plans, results and logs. Check that the tested environment matches current code, then author fresh feasibility votes. Do not directly convert a supported result into a feasible candidate, remove unrelated uncertainties or treat a failed or unrun probe as compatibility proof. Preserve the user's pilot scope and any deferred production rollout.

package/runtime/prompts/profiles/implementation-planning.md

@@ -220,6 +220,7 @@ roles:
     - **Why enumeration is the scale gate.** The number of stages a plan carries is not bounded by any threshold — a genuinely large requirement may need many, and okstra does not guess a ratio. What IS bounded is how cheaply a plan can *claim* coverage of them: one `Stages 1-64` cell used to satisfy the reverse check for the whole map while the planner confirmed nothing, so scale grew for free. Enumeration prices it — every stage you claim costs you the act of naming it and asking whether this requirement is really satisfied there. A plan that cannot bring itself to type the numbers is telling you the stages are not all needed. The typing is the confirmation, so do not batch it mechanically: a row listing `Stages 1, 2, 3, ..., 12` you did not check one by one is the same rubber stamp with more characters.
     - Because that reader only sees prose, it still cannot tell a citation from a mention: `Stage 1 (superseded by Stage 2)` counts Stage 1 as cited. Cite the stages a requirement is actually satisfied by, not stages merely mentioned.
   - **Requirement Coverage (mandatory, §5.5.8):** selected-direction plans preserve the original requirement IDs and link each row to `stageRefs`, `stepRefs`, `validationRefs`, and `fileRefs`; exact forward and reverse coverage is enforced by `validate_selected_direction_plan`. Legacy candidate-comparison plans retain one `R-NNN` row per concrete requirement and the existing Option Candidate plus Stage/Step `coveredBy` semantics. The exact `P-Req-*` queue comes from `scripts/okstra_ctl/plan_items.py` in both branches.
+  - Selected-direction requirements assigned to another project use `status: externally-tracked` with `crossProjectDependencyRefs` pointing to complete, unique `XP-*` rows. Their local stage/step/validation/file references may be empty; mixed requirements retain their actual local references. This counts planned responsibility, never completed work: preserve unresolved execution evidence in `endStateCoverage`. Missing, duplicate or incomplete dependencies fail `implementation_direction._coverage_reference_errors`; schema validation requires external references and keeps all local references mandatory for local-only coverage.
   - **Every coverage and validation row states the stages it belongs to.** Put the stage numbers in `stageRefs` on each `### Requirement Coverage` row and each `### Validation Checklist` row — the same integers the row's `Covered by` prose or its check already names. `coveredBy` stays as it is; this is the machine-readable form of the same fact.
 
     Prose is not a substitute. Reading a stage out of `Covered by` needs a regular expression over a sentence, and a gate cannot be scored on that. Without the field, every requirement and validation row counts against whatever stage is being started, including rows that belong only to stages already finished or not yet begun — measured on one run, that is 9 of 13 blockers, 6 of them on frozen stages no amount of planning can close.

package/runtime/prompts/profiles/technical-verification.md

@@ -0,0 +1,53 @@
+# Technical Verification Profile
+
+```yaml
+roles:
+  - role: analyser
+    min: 2
+    recommended: 2
+    max: 5
+    duty: technical-verification-worker
+  - role: critic
+    min: 0
+    recommended: 1
+    max: 1
+    duty: scope-critic
+  - role: report-writer
+    min: 1
+    recommended: 1
+    max: 1
+    duty: report-writer
+  - role: verifier
+    min: 0
+    recommended: 0
+    max: 0
+    duty: reverification-worker
+    dynamic: true
+```
+
+- Purpose: collect experimental evidence for unresolved technical facts before a new implementation comparison.
+- Required workers:
+  - claude
+  - codex
+  - report-writer
+{{INCLUDE:_common-contract.md}}
+
+## Input and experiment procedure
+
+1. Read the frozen technical input linked in the analysis packet. Preserve the source hash, candidate IDs and fact identities. `resolve_technical_verification_input` enforces same-task source ownership, schema validity, eligible technical facts and unresolved user-decision gates.
+2. Before executing a probe, write its plan under `experiments/<seq>/<worker-id>/`: hypothesis, procedure, commands, confirming and rejecting signals, environment, and inconclusive criteria. Retain the plan with the evidence.
+3. Create a separate source copy in that directory. Record the source commit and any uncommitted input differences. Read the project and task worktree as inputs; perform source edits, installations and builds only in your own copy. Do not share writable dependency directories or use real credentials. Use synthetic local accounts for request-boundary experiments.
+4. Preserve the baseline lockfile. When the hypothesis needs a deliberate dependency change, retain the resulting lockfile and diff, then use a frozen install against that experimental lockfile. Record command, working directory, stdout/stderr and exit code in run-local logs. Distinguish infrastructure failure from a falsified compatibility claim.
+5. Classify each fact as `supported`, `refuted`, `inconclusive` or `not-run` using the declared signals. A zero exit code alone does not establish compatibility. Record limitations and all failed or unavailable probes.
+6. During convergence, inspect plans and logs; rerun disputed probes in a separate copy when feasible. An independent report is not a substitute for command evidence.
+
+Copy boundaries and pre-execution plans are worker instructions reviewed during convergence. The report validator checks fact completeness, run-local log files, experiment working directories and zero exit codes for supported results. It does not sandbox arbitrary shell commands or prove that a declared command produced its log.
+
+## Deliverable and handoff
+
+Copy `sourceReport`, `sourceDataSha256` and `scope` from the frozen input into `technicalVerification`. Emit exactly one check per fact, preserving its `id`, `candidateId`, `factIndex` and `fact`. Each check records its hypothesis, procedure, signals, command evidence, observation, status and limitations. Use project-relative evidence paths. Mark contested results inconclusive.
+
+Route only to `implementation-option-selection`, with one matching phase-continuation follow-up. The next comparison consumes this report through `--clarification-response` and authors fresh feasibility votes. Do not edit the source comparison, clear unrelated uncertainties, rank candidates, approve implementation, merge code or expand the user's pilot scope.
+
+`validate_technical_verification_report` checks frozen-input identity and evidence before publication and during run validation. The report schema restricts the routing target and requires `frontmatter.approved=false`.
+{{INCLUDE:_coverage-critic.md}}

package/runtime/prompts/wizard/prompts.ko.json

@@ -620,7 +620,7 @@
       "echo_template": "edit-target: {value}"
     },
     "role_models": {
-      "label": "{role} 역할의 모델을 고르세요 — 고른 만큼 인스턴스를 띄웁니다 ({range}). 앞줄 추천은 프로젝트 modelDefaults(없으면 카탈로그 기본값) 순서입니다",
+      "label": "{role} 역할의 모델을 고르세요 — 고른 만큼 인스턴스를 띄웁니다 ({range}). 제공자별로 표시하며 추천은 프로젝트 modelDefaults(없으면 카탈로그 기본값)를 따릅니다",
       "echo_template": "role-models: {value}",
       "options": {
         "model": "{model_ref} — {display}",
@@ -646,6 +646,7 @@
   },
   "confirmation": {
     "header": "선택 확인:",
+    "translation_scope": "  번역 작업자: {model} — 보고서 작성자와 같은 제공자·모델을 사용합니다. 선택 언어의 보고서가 필요하면 보고서 본문과 관련 분석·검증 결과를 전달해 번역하고 최종 보고서를 생성합니다. 같은 작업 범위의 재검증·수정·재시도에도 위에서 선택한 제공자·모델을 사용합니다.",
     "provider_data_scope": "\n전달 대상: 위 역할·모델 목록의 제공자(현재 세션 및 선택한 외부 모델 제공자).\n전달 자료: `{project_root}`의 이 작업에 대한 작업 개요, 작업 수행에 필요한 저장소 소스·문서, 선택한 근거 자료 및 실행 중 생성되는 관련 분석·검증 결과.\n진행을 선택하면 위 대상에 해당 자료를 전달하여 선택한 작업을 실행하는 것을 승인합니다. 선택에 없는 제공자나 작업과 무관한 자료는 승인 범위에 포함되지 않습니다. 실행 환경의 권한 검토는 별도로 적용됩니다.",
     "static_role": "  static-role   : {role}#{ordinal} / {model}",
     "dynamic_role": "  dynamic-role  : {role} / reuse selected participant model",

package/runtime/python/okstra_ctl/adapters/hosts/claude-code/relay.md

@@ -196,17 +196,17 @@ The `confirm` prompt's `label` is the selection summary (one line per resolved i
 
 ## Completion, cleanup, and resume
 
-- Follow the core Result Path + terminal-status completion contract. The Claude adapter's wake mechanism is one `Bash(run_in_background: true)` poll covering every pending Result Path, not foreground sleep or an idle-notification dependency. A spawn acknowledgement is never completion.
+- Follow the core Result Path + terminal-status completion contract. Start one `okstra worker-liveness --wait` background command for the pending native worker selectors; CLI batches are awaited by their dispatcher or `okstra team await`. Await the background handle through the current host's completion notification or blocking wait when available. A spawn acknowledgement is never completion.
 - The background poll uses a per-worker deadline of twice the expected duration: 20 minutes for `requirements-discovery`, 30 for `error-analysis`, 40 for `implementation-planning`, 40 for `implementation`, and 20 for `final-verification`. On timeout, record terminal status and apply the core's single shared retry budget.
 - Each in-process worker heartbeat audit sidecar must update at least every five minutes while its result is pending. A missing or stale heartbeat consumes the same one-retry budget; after the second silent hang, record `timeout`. The result file remains the authoritative completion signal.
-- **The background poll checks liveness, not only Result Paths.** Result Paths change once, at the very end, so polling them alone pays the full deadline for a worker that died at minute three. Each poll iteration MUST also run, in the same background shell, one `okstra worker-liveness` call covering every pending worker — one paired `--team-state <path> --worker <id>` per worker, in-process and CLI-wrapper alike. The probe reads that worker row's `livenessMode` to pick the artifact and its `startedAt` as the grace anchor; never pass an artifact path yourself and never infer the transport from provider or filename. It exits non-zero when a worker is `stalled` (heartbeat older than the cadence budget) or `did-not-launch`; either verdict ends the wait for that worker immediately and spends the core's one-retry budget, rather than waiting out the deadline. The command reports only — it never kills or re-dispatches. It shares its heartbeat budget with the Phase 7 audit (`okstra_ctl.worker_heartbeat`), so a worker the live probe passes cannot fail the post-hoc one for cadence. A `stalled` verdict is confirmed before it is returned — the probe waits half the stage's budget and re-reads, so a worker that is merely slow gets to prove it by appending its next heartbeat. Budget that confirmation window into the poll iteration; it is the price of not spending the one-retry budget on a live worker.
-- The Claude Code harness blocks long foreground sleeps and shorter-sleep circumvention loops. Keep the result poll in a single background shell and let wrapper agents use their documented `BashOutput` loop.
+- The single `worker-liveness --wait` command checks live worker evidence as well as Result Paths. Supply paired `--team-state <path> --dispatch-id <id>` selectors (`--worker <id>` only for an unambiguous legacy record). Its existing grace, cadence, stall confirmation, and timeout checks remain active inside that process. It reports the terminal verdict; the lead applies the shared retry budget.
+- Keep the wait in one background shell. When the host yields without a state change, resume the same handle through its supported wait interface; do not start another poll or reread logs.
 - On approved cleanup, reconcile the current live session roster before sending shutdown requests. Never target the lead session.
 - Collect usage before teardown. Resume through the recorded Claude session id and keep all run artifacts authoritative.
 
 ### CLI process polling
 
-- Start `okstra worker-dispatch` with `Bash(run_in_background: true)` and poll `BashOutput(bash_id)` back-to-back until terminal completion. The deterministic dispatcher starts the registered provider script after metadata verification. Never add a foreground sleep.
+- Start `okstra worker-dispatch` with `Bash(run_in_background: true)` and retain the handle until terminal completion. Prefer the host's completion notification or blocking wait; if it yields early, resume the same handle with the supported wait interval. The deterministic dispatcher starts the registered provider script after metadata verification.
 - Return accumulated stdout on success. On a non-zero `exit_code`, record the real code and observed duration.
 - At the 1800-second cap, inspect the live log mtime once. Recent output grants one extension to 2100 seconds; otherwise call `KillShell(shell_id)`, record exit code 124, and return the wrapper timeout sentinel.
 - Keep the background process handle until the provider process reaches terminal state.

package/runtime/python/okstra_ctl/adapters/hosts/codex/relay.md

@@ -190,6 +190,8 @@ If preparation has already failed with a Git lock creation error or `Operation n
 
 ### Permission at the dispatch boundary
 
+Read `runManifest.userAuthorization` before a live dispatch, including `report-finalize`, which can start the translator internally. It preserves the confirmation text and the user response relayed through the wizard; quote its relevant recipient/material scope and response in the execution justification alongside the prepared assignment. The translator reuses the report writer's provider/model, as disclosed at confirmation. Do not wait until translation to inspect that authorization. A missing record is not consent, and the record does not override a host rejection. If review reports missing evidence already present in the record, submit that existing evidence through the permitted review mechanism; ask the user only when the actual approved scope does not cover the dispatch.
+
 Before a live CLI worker dispatch, check the current host's declared sandbox and approval policy. In a restricted Codex session, request the host's supported execution permission on the dispatch command itself (`sandbox_permissions: "require_escalated"` for `exec_command` when that mechanism is available and permitted). Scope the request to the prepared run and explain that it starts the selected worker processes. Follow the host's approval decision; a wizard confirmation or a successful preflight does not grant this permission.
 
 Carry the user's existing authorization into that request: identify the task, the selected providers/models from the prepared assignments, and the task brief, relevant repository source/documents, selected evidence, and related run results those workers will process. Cite the actual `Proceed` response and the data-transfer scope displayed in that confirmation; `outcome.confirmationText` is the runtime's summary reference, not proof by itself that the user saw or accepted it. Explain this scope in the execution tool's justification rather than describing only process startup. Data-transfer authorization and host execution privileges are separate: preserve the former while requesting the latter.

package/runtime/python/okstra_ctl/adapters/providers/zai/adapter.py

@@ -1,7 +1,11 @@
 """Claude Code 실행기를 사용하는 Z.ai GLM 작업자."""
 import os
+import re
+import shlex
+from collections.abc import Mapping
 from dataclasses import replace
-from typing import Any, Mapping
+from pathlib import Path
+from typing import Any
 
 from okstra_ctl.adapters.providers.claude.adapter import ClaudeExecution
 from okstra_ctl.domain.provider import ModelSpec, ProviderSpec, ServedModelAttestation
@@ -10,12 +14,13 @@ from okstra_ctl.domain.worker_exec import ExecCommand, PolicySupport, WorkerExec
 from okstra_ctl.domain.worker_presentation import JsonEvents
 from okstra_ctl.domain.worker_stream import content_block_events
 
-
 ZAI_MODELS = {
-    name: ModelSpec(name, label, name)
-    for name, label in (
-        ("glm-5.3", "GLM-5.3"),
-        ("glm-5.3-flash", "GLM-5.3 Flash"),
+    # 입력·캐시 입력·출력 USD/100만 토큰, 2026-09-14 공식 단가 확인.
+    # https://docs.z.ai/guides/overview/pricing
+    name: ModelSpec(name, label, name, pricing=pricing)
+    for name, label, pricing in (
+        ("glm-5.3", "GLM-5.3", (1.40, 0.26, 4.40)),
+        ("glm-5.3-flash", "GLM-5.3 Flash", (0.15, 0.03, 0.50)),
     )
 }
 
@@ -41,11 +46,39 @@ def observe_usage(event: Mapping[str, Any]) -> Mapping[str, Any] | None:
     return usage if isinstance(usage, Mapping) and usage else None
 
 
+def _read_zai_api_key() -> str:
+    """별도 창에서도 동일한 홈 파일을 읽으며 다른 항목은 환경에 넣지 않는다."""
+    api_key = os.environ.get("ZAI_API_KEY", "").strip()
+    if api_key:
+        return api_key
+    try:
+        lines = (Path.home() / ".env").read_text(encoding="utf-8-sig").splitlines()
+    except FileNotFoundError:
+        # expected-miss: 홈 파일 없이 환경 변수만 사용하는 설치도 지원한다.
+        lines = []
+    except (OSError, UnicodeError):
+        raise OSError("Cannot read ZAI_API_KEY from ~/.env") from None
+    for line in lines:
+        match = re.fullmatch(r"\s*(?:export\s+)?ZAI_API_KEY\s*=\s*(.*)", line)
+        if match is None:
+            continue
+        try:
+            values = shlex.split(match.group(1), comments=True, posix=True)
+        except ValueError:
+            raise OSError(
+                "Invalid ZAI_API_KEY in ~/.env: use a single-line value"
+            ) from None
+        if len(values) > 1:
+            raise OSError("Invalid ZAI_API_KEY in ~/.env: use a single-line value")
+        api_key = values[0].strip() if values else ""
+    if not api_key:
+        raise OSError("ZAI_API_KEY is required in the process environment or ~/.env")
+    return api_key
+
+
 class ZaiExecution:
     def build_command(self, request: WorkerExecRequest) -> ExecCommand:
-        api_key = os.environ.get("ZAI_API_KEY", "").strip()
-        if not api_key:
-            raise OSError("ZAI_API_KEY is required for Z.ai GLM workers")
+        api_key = _read_zai_api_key()
         command = ClaudeExecution().build_command(request)
         return replace(
             command,

package/runtime/python/okstra_ctl/agent/invocation.py

@@ -28,6 +28,7 @@ AgentAudience = Literal[
     "analysis-worker",
     "discovery-worker",
     "diagnosis-worker",
+    "technical-verification-worker",
     "planning-worker",
     "direction-selection-worker",
     "implementation-executor",
@@ -533,6 +534,16 @@ def load_duty_catalog(duty_root: Path) -> dict[AgentAudience, DutyContract]:
     return catalog
 
 
+def load_role_duty_contract(duty_root: Path, audience: AgentAudience) -> DutyContract:
+    """현재 호출의 지침만 읽어 이후 추가된 역할을 기존 실행에 요구하지 않는다."""
+    if audience not in _SUPPORTED_AUDIENCES:
+        raise AgentInvocationError(f"unknown duty audience: {audience}")
+    duty = _load_role_duty(duty_root / f"{audience}.md")
+    if duty.applies_to != audience:
+        raise AgentInvocationError(f"duty audience does not match requested audience: {audience}")
+    return duty
+
+
 def digest_duty_catalog(duty_root: Path) -> str:
     """Return the canonical digest of every duty file in a snapshot."""
     names = [path.relative_to(duty_root).as_posix() for path in duty_root.glob("*.md")]
@@ -722,8 +733,7 @@ def compose_unbound_run_prompt(request: AgentInvocationRequest) -> bytes:
     _validate_common_request(request)
     _validate_unbound_v2_run_request(request)
     common = load_common_duty_contract(request.duty_root)
-    catalog = load_duty_catalog(request.duty_root)
-    duty = catalog[request.audience]
+    duty = load_role_duty_contract(request.duty_root, request.audience)
     return _render_prompt(request, common, duty).encode("utf-8")
 
 
@@ -1037,8 +1047,7 @@ def _utc_seconds(value: datetime) -> str:
 
 def _materialize(request: AgentInvocationRequest) -> _MaterializedInvocation:
     common = load_common_duty_contract(request.duty_root)
-    catalog = load_duty_catalog(request.duty_root)
-    duty = catalog[request.audience]
+    duty = load_role_duty_contract(request.duty_root, request.audience)
     if _request_identity_version(request) == 2 and request.duty_id != duty.id:
         raise AgentInvocationError("v2 execution identity duty does not match audience")
     metadata = _metadata_payload(request, duty, {})
@@ -2109,8 +2118,7 @@ def _verify_duty_snapshot(
     try:
         root = _project_path(project_root, source["dutyRootPath"], must_exist=True)
         common = load_common_duty_contract(root)
-        catalog = load_duty_catalog(root)
-        duty = catalog[duty_contract["id"]]
+        duty = load_role_duty_contract(root, duty_contract["id"])
     except (AgentInvocationError, KeyError):
         return ["duty snapshot is invalid"]
     errors = _verify_duty_metadata(duty_contract, duty)

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

@@ -137,14 +137,15 @@ def _add_materialize_parser(commands: argparse._SubParsersAction) -> None:
 
     apply = commands.add_parser(
         "apply-corrections",
-        help="apply a report-writer corrections ledger of replace/remove "
+        help="apply a report-writer corrections ledger of replace/remove/add/move "
              "entries to the narrative without a writer round and record a "
-             "lead-correction-applied activity row; a ledger with rewrite "
-             "entries or any defect is refused",
+             "lead-correction-applied activity row; rewrite entries require "
+             "--rewrite-results; any remaining defect is refused",
     )
     _common_paths(apply)
     apply.add_argument("--run-manifest", required=True)
     apply.add_argument("--corrections", required=True)
+    apply.add_argument("--rewrite-results", help="JSON replacement values for every rewrite id, with the base narrative SHA-256")
     apply.add_argument("--json", action="store_true")
 
     verify = commands.add_parser("verify")

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

@@ -6,16 +6,17 @@
 analyser)은 작성자가 받는 합성 묶음에서 가져온다 — 두 소비자가 다른 규칙을 보지
 않게 하기 위해서다.
 
-`apply-corrections` 는 replace·remove 만 있는 원장을 작성자 라운드 없이 서사에
-쓰고 활동 원장에 `lead-correction-applied` 행을 남긴다. 선례는 implementation-
-planning 의 planner self-fix 기록(`plan_items_cli._record_self_fixes`)이다.
+`apply-corrections` 는 replace·remove·add·move 와 계산된 단계 수를 직접 적용한다.
+rewrite 는 작성자가 제출한 교체 값을 대조한 뒤 적용하고, 활동 원장에
+`lead-correction-applied` 행과 교체 값 파일 근거를 남긴다.
 """
 from __future__ import annotations
 
 import os
 from pathlib import Path
+import runpy
 import tempfile
-from typing import Any, Mapping
+from typing import Any, Callable, Mapping
 
 from ..activity import (
     ActivityProjectionError,
@@ -23,6 +24,7 @@ from ..activity import (
     record_activity,
 )
 from ...final_report_schema import load_schema_version
+from ...json_boundary import load_owned_object
 from ...implementation_options import validate_implementation_option_selection
 from ...report_contract import TASK_TYPE_DATA_PROPERTY
 from ...report_assembly import validate_plan_draft
@@ -33,8 +35,11 @@ from ...report_corrections import (
     render_applied_narrative,
 )
 from ...report_inputs import report_narrative_path, uses_report_contract_v3
+from ...paths import STAGE_VALIDATOR_RELATIVE, find_asset_root
+from ...report_narrative import task_narrative_errors
 from ...report_synthesis_packet import (
     ReportSynthesisPacketError,
+    ReportSynthesisPacket,
     build_report_synthesis_packet,
 )
 from .inputs import AgentPromptCliError, _authorized_path, _relative
@@ -53,6 +58,7 @@ def run_corrections_check(
     team_state: Mapping[str, Any],
     corrections_path: Path,
     narrative_path: Path,
+    rewrite_results: Mapping[str, Any] | None = None,
 ) -> CorrectionsCheck:
     """원장을 이 run 의 기준 서사에 대조한다. 결함은 `CorrectionsCheck.defects` 에 모인다."""
     ledger, load_defects = load_corrections(corrections_path)
@@ -92,8 +98,26 @@ def run_corrections_check(
             f"reason=synthesis packet source defect: {issue.reason}"
             for issue in exc.issues
         ))
+    return check_corrections(
+        ledger=ledger,
+        base_narrative=base_path.read_text(encoding="utf-8"),
+        schema=load_schema_version("3.0"),
+        block_rules=packet.block_rules,
+        semantic_validator=_correction_semantic_validator(
+            project_root, manifest, narrative_path, packet,
+            rewrite_results is None and any(item.get("kind") == "rewrite" for item in ledger["corrections"]),
+        ),
+        rewrite_results=rewrite_results,
+    )
+
+
+def _correction_semantic_validator(
+    project_root: Path, manifest: Mapping[str, Any], narrative_path: Path,
+    packet: ReportSynthesisPacket, pending_rewrites: bool,
+) -> Callable[[dict[str, Any]], list[str]] | None:
     task_type = str(manifest.get("taskType") or "")
-    semantic_validator = None
+    schema = load_schema_version("3.0")
+    semantic_validator = lambda data: task_narrative_errors(data, schema, task_type)
     if task_type == "implementation-option-selection":
         block_key = TASK_TYPE_DATA_PROPERTY[task_type]
         original_ids = packet.original_requirement_ids
@@ -101,24 +125,31 @@ def run_corrections_check(
 
         def semantic_validator(data: dict[str, Any]) -> list[str]:
             block = data.get(block_key)
-            return [
+            return task_narrative_errors(data, schema, task_type) + [
                 f"{block_key}: {error}"
                 for error in validate_implementation_option_selection(
                     block if isinstance(block, Mapping) else {}, original_ids, analysers,
                 )
             ]
     elif task_type == "implementation-planning":
+        validator_root = find_asset_root(STAGE_VALIDATOR_RELATIVE)
+        if validator_root is None:
+            raise AgentPromptCliError("cannot locate implementation planning validator")
+        stage_validator = runpy.run_path(str(validator_root.joinpath(*STAGE_VALIDATOR_RELATIVE)))
+        granted = stage_validator["user_bypassed_stages_for_plan"](narrative_path)
 
         def semantic_validator(data: dict[str, Any]) -> list[str]:
-            return validate_plan_draft(data, project_root, manifest)
+            planning = data.get("implementationPlanning")
+            stage_errors = [] if pending_rewrites else stage_validator["collect_data_validation_errors"](
+                planning if isinstance(planning, dict) else {}, granted,
+            )
+            return [
+                *task_narrative_errors(data, schema, task_type),
+                *validate_plan_draft(data, project_root, manifest),
+                *[f"implementationPlanning: {error}" for error in stage_errors],
+            ]
 
-    return check_corrections(
-        ledger=ledger,
-        base_narrative=base_path.read_text(encoding="utf-8"),
-        schema=load_schema_version("3.0"),
-        block_rules=packet.block_rules,
-        semantic_validator=semantic_validator,
-    )
+    return semantic_validator
 
 
 def corrections_payload(
@@ -129,11 +160,10 @@ def corrections_payload(
         "ok": check.ok,
         "correctionsPath": _relative(project_root, corrections_path),
         "mechanical": check.mechanical,
+        "baseNarrativeSha256": check.ledger.get("baseNarrativeSha256"),
         "corrections": [
             {
-                "id": item.get("id"),
-                "kind": item.get("kind"),
-                "path": item.get("path"),
+                **item,
                 "constraints": list(check.constraints.get(str(item.get("id")), ())),
             }
             for item in check.corrections
@@ -150,6 +180,7 @@ def run_corrections_apply(
     active_context: Mapping[str, Any],
     team_state: Mapping[str, Any],
     corrections_path: Path,
+    rewrite_results_path: Path | None = None,
 ) -> dict[str, Any]:
     """기계적 원장을 서사에 쓰고 활동 행을 남긴다 — `apply-corrections` 의 본체.
 
@@ -174,6 +205,10 @@ def run_corrections_apply(
             "writer with --corrections instead"
         )
     corrections_rel = _relative(project_root, corrections_path)
+    rewrite_results = (
+        load_owned_object(rewrite_results_path, artifact="report writer rewrite results")
+        if rewrite_results_path is not None else None
+    )
     check = run_corrections_check(
         project_root=project_root,
         manifest=manifest,
@@ -181,7 +216,18 @@ def run_corrections_apply(
         team_state=team_state,
         corrections_path=corrections_path,
         narrative_path=narrative_path,
+        rewrite_results=rewrite_results,
     )
+    return _apply_checked_corrections(
+        project_root, manifest_path, narrative_path, corrections_path, check, rewrite_results_path,
+    )
+
+
+def _apply_checked_corrections(
+    project_root: Path, manifest_path: Path, narrative_path: Path,
+    corrections_path: Path, check: CorrectionsCheck, rewrite_results_path: Path | None,
+) -> dict[str, Any]:
+    corrections_rel = _relative(project_root, corrections_path)
     if check.defects:
         raise AgentPromptCliError(
             "report-writer corrections defects: " + "; ".join(check.defects)
@@ -214,21 +260,36 @@ def run_corrections_apply(
         )
     applied_ids = [str(item.get("id")) for item in check.corrections]
     narrative_rel = _relative(project_root, narrative_path)
-    _write_text_atomic(
-        narrative_path, render_applied_narrative(check, load_schema_version("3.0")),
+    rendered = render_applied_narrative(check, load_schema_version("3.0"))
+    if narrative_path.is_file() and narrative_path.read_text(encoding="utf-8") not in (
+        base_path.read_text(encoding="utf-8"), rendered,
+    ):
+        raise AgentPromptCliError("live narrative changed after the correction base was preserved; create a new ledger")
+    _write_text_atomic(narrative_path, rendered)
+    return _record_correction_application(
+        project_root, manifest_path, narrative_rel, corrections_rel, applied_ids, rewrite_results_path,
     )
+
+
+def _record_correction_application(
+    project_root: Path, manifest_path: Path, narrative_rel: str,
+    corrections_rel: str, applied_ids: list[str], rewrite_results_path: Path | None,
+) -> dict[str, Any]:
     details = {
         "kind": LEAD_CORRECTION_ACTIVITY_KIND,
         "agent": _LEAD_AGENT,
         "summary": (
-            f"Applied {len(applied_ids)} mechanical correction(s) "
+            f"Applied {len(applied_ids)} correction(s) "
             f"({', '.join(applied_ids)}) from {corrections_rel} to the report "
-            "narrative without a writer round"
+            + ("narrative using supplied writer replacements" if rewrite_results_path
+               else "narrative without a writer round")
         ),
         "planItemIds": [],
         "resultPath": narrative_rel,
         "commands": [],
-        "evidenceRefs": [corrections_rel, *applied_ids],
+        "evidenceRefs": [corrections_rel, *applied_ids] + (
+            [_relative(project_root, rewrite_results_path)] if rewrite_results_path else []
+        ),
         "outcome": "completed",
     }
     try:

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

@@ -11,6 +11,7 @@ from __future__ import annotations
 import argparse
 import os
 from pathlib import Path
+import shlex
 import shutil
 import tempfile
 from typing import Any, Mapping, get_args
@@ -51,6 +52,7 @@ from ...report_synthesis_packet import (
 from ...worker_prompt_body import report_writer_input_lines
 from ...dispatch_state import detect_terminal_backend
 from ...report_corrections import (
+    CorrectionsCheck,
     body_owned_section_conflicts,
     render_corrections_section,
     render_output_section,
@@ -325,7 +327,7 @@ def _materialize_run(
     is_reverify = is_verification_dispatch_kind(args.dispatch_kind)
     if is_reverify:
         body = _complete_run_reverify_body(args, manifest, active_context, assignment, body, instruction_path)
-    if args.audience == "report-writer":
+    if args.audience == "report-writer" and not getattr(args, "corrections", None):
         body = _with_inputs_section(
             body,
             _report_writer_input_lines(
@@ -494,6 +496,8 @@ def _with_report_writer_sections(
             base_narrative_rel=str(check.ledger.get("baseNarrativePath") or ""),
             corrections_rel=_relative(project_root, corrections_path),
         ))
+        body = "## Inputs\n\nCorrection-only task: use the checked field values and evidence below."
+        sections.extend(_render_correction_application(args, project_root, narrative_path, corrections_path, check))
         sections.append("")
     else:
         _refuse_free_form_correction(project_root, narrative_path)
@@ -507,6 +511,35 @@ def _with_report_writer_sections(
     return body.rstrip("\n") + "\n\n" + "\n".join(sections) + "\n"
 
 
+def _render_correction_application(
+    args: argparse.Namespace, project_root: Path, narrative_path: Path,
+    corrections_path: Path, check: CorrectionsCheck,
+) -> list[str]:
+    result_path = narrative_path.with_name(f"{narrative_path.stem}.{args.invocation_id}.rewrites.json")
+    command = [
+        "okstra", "agent-prompt", "apply-corrections", "--project-root", str(project_root),
+        "--run-manifest", str(args.run_manifest), "--corrections", str(corrections_path),
+    ]
+    sections: list[str] = []
+    if not check.mechanical:
+        command.extend(["--rewrite-results", str(result_path)])
+        sections.extend([
+            "", f"Write only rewrite replacement values to `{_relative(project_root, result_path)}`:",
+            '{"baseNarrativeSha256":"' + check.ledger["baseNarrativeSha256"]
+            + '","replacements":[{"id":"RC-...","replacement":"the complete value for that field"}]}',
+            "Include every rewrite id exactly once. Do not repeat unchanged narrative fields. "
+            "Use the JSON value type required by each target's schema constraint.",
+        ])
+    sections.extend([
+        "", "Run this command to validate all replacements and generate the complete narrative:",
+        "```sh", shlex.join(command), "```",
+        "The command reports every remaining schema and semantic defect together. "
+        "Repair the replacement values and retry only when it reports a defect. "
+        "Do not write the complete narrative yourself. Then write the pointer record and reading audit.",
+    ])
+    return sections
+
+
 def _preserve_reauthored_narrative(
     project_root: Path, narrative_path: Path, *, invocation_id: str,
 ) -> str | None:
@@ -567,7 +600,7 @@ def _refuse_free_form_correction(project_root: Path, narrative_path: Path) -> No
         "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 "
+        "--corrections here. A ledger of only replace/remove/add/move 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 "
@@ -631,6 +664,14 @@ def _apply_corrections(args: argparse.Namespace) -> dict[str, Any]:
     project_root, manifest_path, manifest, active_context, corrections_path = (
         _corrections_context(args)
     )
+    results_path = None
+    if getattr(args, "rewrite_results", None):
+        contract = _mapping(manifest.get("agentContract"), "agent contract")
+        authorized = _mapping(contract.get("authorizedPaths"), "authorized paths")
+        results_path = _authorized_path(
+            project_root, args.rewrite_results, authorized.get("resultRoots"),
+            "rewrite results", must_exist=True,
+        )
     return run_corrections_apply(
         project_root=project_root,
         manifest=manifest,
@@ -638,6 +679,7 @@ def _apply_corrections(args: argparse.Namespace) -> dict[str, Any]:
         active_context=active_context,
         team_state=_load_team_state(project_root, manifest),
         corrections_path=corrections_path,
+        rewrite_results_path=results_path,
     )