okstra 0.202.0 → 0.204.0

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

@@ -12,7 +12,7 @@ from pathlib import Path
 from pathlib import PurePosixPath
 import re
 import tempfile
-from typing import Iterator, Literal, Mapping, get_args
+from typing import Any, Iterator, Literal, Mapping, get_args
 
 from ..domain.role import RoleCatalogError, role_for_duty
 from ..json_boundary import (
@@ -44,34 +44,6 @@ AgentAudience = Literal[
 ]
 
 _SUPPORTED_AUDIENCES = frozenset(get_args(AgentAudience))
-# The section set IS the duty contract's shape: a duty author adding a role file
-# reads these names, and `_validate_duty_sections` refuses a file that misses one.
-# The check is structural — it proves every required section exists and carries
-# text, NOT that the text is a real contract. A one-line placeholder passes it;
-# what keeps a section substantive is review, and the rule that earns a section a
-# place here at all: a sentence that reads the same in another duty file belongs
-# in `common.md` or nowhere.
-COMMON_DUTY_SECTIONS = (
-    "Assignment fidelity",
-    "Required inputs",
-    "Evidence first",
-    "Authority and scope",
-    "Collaboration and independence",
-    "Instruction precedence",
-    "Conflict handling",
-    "Completion honesty",
-)
-ROLE_DUTY_SECTIONS = (
-    "Responsibility",
-    "Required conduct",
-    "Decision principles",
-    "Authority and boundaries",
-    "Evidence standard",
-    "Collaboration contract",
-    "Completion criteria",
-    "Forbidden conduct",
-    "Blocked-state reporting",
-)
 _SLUG_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
 _DUTY_SECTION_RE = re.compile(r"(?m)^## ([^\n]+)\s*$")
 _TOP_LEVEL_KEYS = {
@@ -144,6 +116,8 @@ class DutyContract:
     applies_to: AgentAudience | None
     body: str
     source_path: Path
+    # 직무가 선언한 정본 역할. 공통 계약과 역할 계약 자신은 갖지 않는다.
+    role_id: str = ""
 
 
 @dataclass(frozen=True)
@@ -495,21 +469,102 @@ class _MaterializedInvocation:
     reservation: dict[str, object] | None
 
 
+
+# 계약 JSON 을 프롬프트에 실을 Markdown 으로 바꾸는 고정 렌더러. 제목과 순서는
+# 스키마 필드 순서에 고정되어 있고, 빈 배열도 섹션을 생략하지 않는다 — 생략하면
+# 같은 계약이 호출마다 다른 다이제스트를 갖는다.
+_COMMON_DUTY_SECTIONS_JSON = (
+    ("assignmentFidelity", "Assignment fidelity"),
+    ("requiredInputs", "Required inputs"),
+    ("evidenceFirst", "Evidence first"),
+    ("authorityAndScope", "Authority and scope"),
+    ("collaborationAndIndependence", "Collaboration and independence"),
+    ("instructionPrecedence", "Instruction precedence"),
+    ("conflictHandling", "Conflict handling"),
+    ("completionHonesty", "Completion honesty"),
+)
+_ROLE_CONTRACT_SECTIONS_JSON = (
+    ("identity", "Identity"),
+    ("responsibilities", "Responsibility"),
+    ("requiredCapabilities", "Required capabilities"),
+    ("prohibitions", "Prohibitions"),
+)
+_ROLE_DUTY_SECTIONS_JSON = (
+    ("responsibilities", "Responsibility"),
+    ("requiredConduct", "Required conduct"),
+    ("decisionPrinciples", "Decision principles"),
+    ("authorityAndBoundaries", "Authority and boundaries"),
+    ("evidenceStandards", "Evidence standard"),
+    ("collaborationContract", "Collaboration contract"),
+    ("completionCriteria", "Completion criteria"),
+    ("prohibitions", "Forbidden conduct"),
+    ("blockedStateReporting", "Blocked-state reporting"),
+)
+
+
+def _contract_title(contract_id: str) -> str:
+    return " ".join(part.capitalize() for part in contract_id.split("-"))
+
+
+def _render_contract_body(
+    payload: Mapping[str, Any],
+    sections: tuple[tuple[str, str], ...],
+    heading: str,
+    path: Path,
+) -> str:
+    lines = [f"# {heading}", ""]
+    for key, title in sections:
+        values = payload.get(key)
+        if not isinstance(values, list) or not all(
+            isinstance(item, str) and item.strip() for item in values
+        ):
+            raise AgentInvocationError(f"invalid contract field {key!r}: {path}")
+        lines.append(f"## {title}")
+        lines.append("")
+        if values:
+            lines.extend(f"- {item}" for item in values)
+        else:
+            lines.append("- (none)")
+        lines.append("")
+    return "\n".join(lines).rstrip("\n") + "\n"
+
+
+def _load_contract_payload(path: Path) -> Mapping[str, Any]:
+    if not path.is_file() and path.with_suffix(".md").is_file():
+        # 이 run 은 Markdown 직무를 동결했다(contractFormatVersion 1). 그 형식의
+        # 파서는 제거됐으므로 여기서 멈추고 원인을 이름한다 — 없는 파일 이름만
+        # 알리면 설치가 깨진 것처럼 읽힌다.
+        raise AgentInvocationError(
+            f"run froze markdown duty contracts and cannot be resumed: {path.parent}"
+        )
+    try:
+        payload = load_owned_object(path, artifact="agent contract")
+    except JsonBoundaryError as exc:
+        raise AgentInvocationError(f"invalid agent contract: {path}: {exc}") from exc
+    except OSError as exc:
+        raise AgentInvocationError(f"cannot read agent contract: {path}") from exc
+    if payload.get("schemaVersion") != "1.0":
+        raise AgentInvocationError(f"unsupported contract schemaVersion: {path}")
+    return payload
+
+
 def load_common_duty_contract(duty_root: Path) -> DutyContract:
     """Load the common fragment, which is deliberately outside the role catalog."""
-    path = duty_root / "common.md"
-    fields, body = _parse_duty_file(path)
-    if set(fields) != {"id", "version", "kind"}:
-        raise AgentInvocationError(f"invalid common duty frontmatter: {path}")
-    if fields["id"] != "common" or fields["kind"] != "common":
-        raise AgentInvocationError(f"invalid common duty frontmatter: {path}")
-    _validate_duty_sections(body, COMMON_DUTY_SECTIONS, "common", path)
+    path = duty_root / "common.json"
+    payload = _load_contract_payload(path)
+    if payload.get("id") != "common":
+        raise AgentInvocationError(f"invalid common contract id: {path}")
     return DutyContract(
         id="common",
-        version=_parse_version(fields["version"], path),
+        version=1,
         kind="common",
         applies_to=None,
-        body=body,
+        body=_render_contract_body(
+            payload,
+            _COMMON_DUTY_SECTIONS_JSON,
+            "Common Agent Duty Contract",
+            path,
+        ),
         source_path=path,
     )
 
@@ -518,8 +573,8 @@ def load_duty_catalog(duty_root: Path) -> dict[AgentAudience, DutyContract]:
     """Load one role contract for every supported invocation audience."""
     catalog: dict[AgentAudience, DutyContract] = {}
     seen_ids: set[str] = set()
-    for path in sorted(duty_root.glob("*.md")):
-        if path.name == "common.md":
+    for path in sorted(duty_root.glob("*.json")):
+        if path.name == "common.json":
             continue
         duty = _load_role_duty(path)
         if duty.id in seen_ids:
@@ -538,18 +593,49 @@ def load_role_duty_contract(duty_root: Path, audience: AgentAudience) -> DutyCon
     """현재 호출의 지침만 읽어 이후 추가된 역할을 기존 실행에 요구하지 않는다."""
     if audience not in _SUPPORTED_AUDIENCES:
         raise AgentInvocationError(f"unknown duty audience: {audience}")
-    duty = _load_role_duty(duty_root / f"{audience}.md")
+    duty = _load_role_duty(duty_root / f"{audience}.json")
     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")]
+    """Return the canonical digest of every contract file in a snapshot.
+
+    역할 계약은 하위 `roles/` 에 둔다 — `report-writer` 와 `translator` 는 직무
+    id 이면서 역할 id 라, 한 폴더에 두면 두 계약이 같은 파일 이름을 두고 겹친다.
+    """
+    names = [
+        path.relative_to(duty_root).as_posix()
+        for path in (*duty_root.glob("*.json"), *(duty_root / "roles").glob("*.json"))
+    ]
     return _digest_framed_files(duty_root, names)
 
 
+def load_role_contract(duty_root: Path, role_id: str) -> DutyContract:
+    """이 호출의 역할 계약. 직무가 `roleId` 로 이름한 역할 하나만 읽는다."""
+    path = duty_root / "roles" / f"{role_id}.json"
+    payload = _load_contract_payload(path)
+    if payload.get("id") != role_id:
+        raise AgentInvocationError(f"role contract id does not match its file: {path}")
+    identity = payload.get("identity")
+    if not isinstance(identity, str) or not identity.strip():
+        raise AgentInvocationError(f"role contract has no identity: {path}")
+    return DutyContract(
+        id=role_id,
+        version=1,
+        kind="role",
+        applies_to=None,
+        body=_render_contract_body(
+            {**payload, "identity": [identity]},
+            _ROLE_CONTRACT_SECTIONS_JSON,
+            f"{_contract_title(role_id)} Role Contract",
+            path,
+        ),
+        source_path=path,
+    )
+
+
 def prepare_agent_invocation(
     request: AgentInvocationRequest,
 ) -> PreparedAgentInvocation:
@@ -1314,7 +1400,10 @@ def _render_prompt(
     if assignment.host_model_value is not None:
         header.append(f"**Host model value:** {assignment.host_model_value}")
     header.extend(delivery)
-    duty_body = f"{common.body.rstrip()}\n\n{duty.body.rstrip()}"
+    role_contract = load_role_contract(request.duty_root, duty.role_id)
+    duty_body = "\n\n".join(
+        part.rstrip() for part in (common.body, role_contract.body, duty.body)
+    )
     return (
         "\n".join(header)
         + "\n\n## Duty Contract\n\n"
@@ -1344,7 +1433,11 @@ def _invocation_digests(
             _source_payload(source) for source in request.instruction.source_paths
         ],
     }
-    selected_names = ["common.md", duty.source_path.name]
+    selected_names = [
+        "common.json",
+        f"roles/{duty.role_id}.json",
+        duty.source_path.name,
+    ]
     return {
         "catalogDigest": digest_duty_catalog(request.duty_root),
         "assignmentDigest": _sha256(_canonical_json(assignment)),
@@ -2131,7 +2224,9 @@ def _verify_duty_snapshot(
     if actual_catalog != expected_catalog or digests["catalogDigest"] != actual_catalog:
         errors.append("catalog digest does not match run duty snapshot")
         return errors
-    actual_duty = _digest_framed_files(root, ["common.md", duty.source_path.name])
+    actual_duty = _digest_framed_files(
+        root, ["common.json", f"roles/{duty.role_id}.json", duty.source_path.name]
+    )
     if digests["dutyDigest"] != actual_duty:
         errors.append("duty digest does not match run duty snapshot")
         return errors
@@ -2163,7 +2258,17 @@ def _verify_prompt_duty_body(
         rendered_duty, _task = remainder.split("\n\n## Task Instructions\n\n", 1)
     except (AgentInvocationError, OSError, UnicodeDecodeError, ValueError):
         return ["prompt duty contract does not match duty snapshot"]
-    expected = f"{common.body.rstrip()}\n\n{duty.body.rstrip()}"
+    role_contract = load_role_contract(
+        _project_path(
+            project_root,
+            str(metadata["contractSource"]["dutyRootPath"]),
+            must_exist=True,
+        ),
+        duty.role_id,
+    )
+    expected = "\n\n".join(
+        part.rstrip() for part in (common.body, role_contract.body, duty.body)
+    )
     if rendered_duty != expected:
         return ["prompt duty contract does not match duty snapshot"]
     return []
@@ -2407,77 +2512,27 @@ def _deduplicate(errors: list[str]) -> list[str]:
 
 
 def _load_role_duty(path: Path) -> DutyContract:
-    fields, body = _parse_duty_file(path)
-    if set(fields) != {"id", "version", "kind", "appliesTo"}:
-        raise AgentInvocationError(f"invalid role duty frontmatter: {path}")
-    audience = fields["appliesTo"]
-    if audience not in _SUPPORTED_AUDIENCES:
+    payload = _load_contract_payload(path)
+    audience = payload.get("id")
+    if not isinstance(audience, str) or audience not in _SUPPORTED_AUDIENCES:
         raise AgentInvocationError(f"unknown duty audience: {audience}")
-    if fields["kind"] != "role" or fields["id"] != audience:
-        raise AgentInvocationError(f"invalid role duty frontmatter: {path}")
-    _validate_duty_sections(body, ROLE_DUTY_SECTIONS, "role", path)
+    if audience != path.stem:
+        raise AgentInvocationError(f"duty id does not match its file name: {path}")
+    if not isinstance(payload.get("roleId"), str) or not payload["roleId"]:
+        raise AgentInvocationError(f"duty contract has no roleId: {path}")
     return DutyContract(
-        id=fields["id"],
-        version=_parse_version(fields["version"], path),
+        role_id=payload["roleId"],
+        id=audience,
+        version=1,
         kind="role",
         applies_to=audience,
-        body=body,
+        body=_render_contract_body(
+            payload,
+            _ROLE_DUTY_SECTIONS_JSON,
+            f"{_contract_title(audience)} Duty Contract",
+            path,
+        ),
         source_path=path,
     )
 
 
-def _parse_duty_file(path: Path) -> tuple[dict[str, str], str]:
-    try:
-        text = path.read_text(encoding="utf-8")
-    except OSError as exc:
-        raise AgentInvocationError(f"cannot read duty contract: {path}") from exc
-    lines = text.splitlines(keepends=True)
-    if not lines or lines[0].strip() != "---":
-        raise AgentInvocationError(f"missing duty frontmatter: {path}")
-    try:
-        end = next(index for index, line in enumerate(lines[1:], 1) if line.strip() == "---")
-    except StopIteration as exc:
-        raise AgentInvocationError(f"unterminated duty frontmatter: {path}") from exc
-    fields: dict[str, str] = {}
-    for line in lines[1:end]:
-        key, separator, value = line.partition(":")
-        if not separator or not key.strip() or key.strip() in fields:
-            raise AgentInvocationError(f"invalid duty frontmatter: {path}")
-        fields[key.strip()] = value.strip()
-    return fields, "".join(lines[end + 1 :]).lstrip("\n")
-
-
-def _validate_duty_sections(
-    body: str,
-    required: tuple[str, ...],
-    kind: str,
-    path: Path,
-) -> None:
-    matches = list(_DUTY_SECTION_RE.finditer(body))
-    sections: dict[str, str] = {}
-    for index, match in enumerate(matches):
-        name = match.group(1).strip()
-        if name in sections:
-            raise AgentInvocationError(f"duplicate {kind} duty section {name}: {path}")
-        end = matches[index + 1].start() if index + 1 < len(matches) else len(body)
-        sections[name] = body[match.end() : end].strip()
-    missing = [name for name in required if name not in sections]
-    if missing:
-        raise AgentInvocationError(
-            f"missing {kind} duty sections: {', '.join(missing)}: {path}"
-        )
-    empty = [name for name in required if not sections[name]]
-    if empty:
-        raise AgentInvocationError(
-            f"empty {kind} duty sections: {', '.join(empty)}: {path}"
-        )
-
-
-def _parse_version(value: str, path: Path) -> int:
-    try:
-        version = int(value)
-    except ValueError as exc:
-        raise AgentInvocationError(f"invalid duty version: {path}") from exc
-    if version < 1:
-        raise AgentInvocationError(f"invalid duty version: {path}")
-    return version

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

@@ -41,6 +41,7 @@ _CLI_EPILOG = r"""Usage:
   okstra agent-prompt verify-completion [options]
   okstra agent-prompt record-dispatch [options]
   okstra agent-prompt link-result [options]
+  okstra agent-prompt refreeze-contracts --project-root <dir> --run-manifest <path> [--json]
 """
 
 
@@ -57,6 +58,12 @@ def _parser() -> argparse.ArgumentParser:
     _add_materialize_parser(commands)
     _add_completion_parsers(commands)
     _add_dispatch_parsers(commands)
+    operation = commands.add_parser(
+        "resolve-operation",
+        help="resolve the role, worker count and models an operation requires",
+    )
+    operation.add_argument("--operation", required=True)
+    operation.add_argument("--json", action="store_true")
     jobs = commands.add_parser("jobs", help="generate a verified jobs file without dispatching")
     _common_paths(jobs)
     jobs.add_argument("--run-manifest", required=True)
@@ -210,6 +217,15 @@ def _add_dispatch_parsers(commands: argparse._SubParsersAction) -> None:
     abandon.add_argument("--reason", required=True)
     abandon.add_argument("--json", action="store_true")
 
+    refreeze = commands.add_parser(
+        "refreeze-contracts",
+        help="re-freeze this run's duty contracts in the installed format "
+             "and stamp the manifest digest",
+    )
+    _common_paths(refreeze)
+    refreeze.add_argument("--run-manifest", required=True)
+    refreeze.add_argument("--json", action="store_true")
+
     link_result = commands.add_parser("link-result")
     _common_paths(link_result)
     link_result.add_argument("--run-manifest", required=True)
@@ -229,9 +245,99 @@ def _standalone_completion_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--json", action="store_true")
 
 
+def _refreeze_contracts(args: argparse.Namespace) -> dict[str, object]:
+    """이 run 의 계약을 설치본 형식으로 다시 동결한다. 사용자만 부른다."""
+    from ...contract_refreeze import (
+        ContractRefreezeError,
+        refreeze_run_contracts,
+    )
+    from ...paths import find_asset_root
+
+    workspace_root = find_asset_root(("prompts", "duties"), is_present=Path.is_dir)
+    if workspace_root is None:
+        raise AgentPromptCliError(
+            "agent duty catalog not found: no prompts/duties under OKSTRA_HOME "
+            "or this checkout"
+        )
+    try:
+        result = refreeze_run_contracts(
+            project_root=Path(args.project_root),
+            run_manifest_path=Path(args.run_manifest),
+            workspace_root=workspace_root,
+        )
+    except ContractRefreezeError as exc:
+        raise AgentPromptCliError(str(exc)) from exc
+    return {
+        "dutyRoot": result.duty_root,
+        "digest": result.digest,
+        "previousDigest": result.previous_digest,
+        "formatVersion": result.format_version,
+        "previousFormatVersion": result.previous_format_version,
+        "changed": result.changed,
+    }
+
+
+def _resolve_operation(operation_id: str) -> dict[str, object]:
+    """이 작업이 열 칸과 각 칸의 모델. 기술은 작업 이름만 알면 된다."""
+    from ...model_pool import ModelPool
+    from ...operation_invocation import (
+        OperationPreparationError,
+        resolve_operation_slots,
+    )
+    from ...paths import find_asset_root
+    from ...registry.provider_registry import default_provider_registry
+
+    root = find_asset_root(("agents", "operations"), is_present=Path.is_dir)
+    if root is None:
+        raise AgentPromptCliError(
+            "operation contracts not found: no agents/operations under "
+            "OKSTRA_HOME or this checkout"
+        )
+    try:
+        slots = resolve_operation_slots(
+            operation_id,
+            contract_root=root,
+            pool=ModelPool.from_registry(default_provider_registry()),
+        )
+    except OperationPreparationError as exc:
+        raise AgentPromptCliError(str(exc)) from exc
+    return {
+        "operation": operation_id,
+        "dutyId": slots[0].duty_id,
+        "roleId": slots[0].role_id,
+        "count": len(slots),
+        "slots": [
+            {
+                "ordinal": slot.ordinal,
+                "provider": slot.provider_id,
+                "modelRef": slot.model_ref,
+                "model": slot.display_name,
+            }
+            for slot in slots
+        ],
+    }
+
+
 def main(argv: list[str] | None = None) -> int:
     try:
         args = _parser().parse_args(argv)
+        if args.command == "resolve-operation":
+            payload = _resolve_operation(args.operation)
+            if args.json:
+                _emit(payload, True)
+            else:
+                # 기본 출력은 고정 텍스트다. 기술 본문이 모델에게 okstra 소유
+                # JSON 을 읽으라고 지시하면 그 해석이 곧 두 번째 파서가 된다.
+                print(f"operation: {payload['operation']}")
+                print(f"duty: {payload['dutyId']}")
+                print(f"role: {payload['roleId']}")
+                print(f"workers: {payload['count']}")
+                for slot in payload["slots"]:
+                    print(
+                        f"  slot {slot['ordinal']}: "
+                        f"provider={slot['provider']} model={slot['modelRef']}"
+                    )
+            return 0
         if args.command == "jobs":
             payload = generate_jobs(args)
             if args.json:
@@ -277,6 +383,20 @@ def main(argv: list[str] | None = None) -> int:
         if args.command == "verify-completion":
             _verify_completion(args)
             return 0
+        if args.command == "refreeze-contracts":
+            payload = _refreeze_contracts(args)
+            if args.json:
+                _emit(payload, True)
+            else:
+                print(f"duty root: {payload['dutyRoot']}")
+                print(f"catalog digest: {payload['digest']}")
+                print(
+                    "contract format: "
+                    f"{payload['previousFormatVersion']} -> {payload['formatVersion']}"
+                    if payload["changed"]
+                    else "contract format: already current"
+                )
+            return 0
         if args.command == "record-dispatch":
             _record_dispatch(args)
             return 0

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

@@ -41,6 +41,16 @@ from ...worker_prompt_policy import (
     is_verification_dispatch_kind,
 )
 from ...paths import okstra_home
+from ...contract_refreeze import (
+    CONTRACT_FORMAT_VERSION,
+    frozen_format_version,
+    refreeze_message,
+)
+from ...initial_prompt_materialization import (
+    InitialPromptMaterializationError,
+    implementation_anchor_lines,
+    required_resource_block,
+)
 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
@@ -300,6 +310,12 @@ def _materialize_run(
         must_exist=True,
     )
     if contract.get("catalogDigest") != digest_duty_catalog(duty_root):
+        # 형식이 바뀐 릴리스를 설치하면 옛 run 의 다이제스트는 영영 맞지 않는다.
+        # "다이제스트 불일치" 만 말하면 읽는 쪽은 파일이 변조된 줄 알고 그 자리를
+        # 뒤진다 — 실측 2026-09-23: 한 세션이 dispatch-kind 별 분기를 찾다가
+        # 멈췄고, 원인은 그 사이에 일어난 설치였다.
+        if frozen_format_version(contract) != CONTRACT_FORMAT_VERSION:
+            raise AgentPromptCliError(refreeze_message(str(duty_root)))
         raise AgentPromptCliError("run duty snapshot catalog digest does not match")
     active_context_path = _project_manifest_path(
         project_root,
@@ -357,6 +373,13 @@ def _materialize_run(
             "--corrections requires report contract 3.0 (a Markdown narrative); "
             "this run uses an older contract"
         )
+    if args.audience in _RESOURCE_AUDIENCES and not is_reverify:
+        anchor_lines = anchor_lines + tuple(
+            _implementation_anchors(project_root, manifest_path, args.worker_id)
+        )
+        body = _with_required_resources(
+            project_root, manifest_path, args.worker_id, body
+        )
     request = AgentInvocationRequest(
         invocation_id=args.invocation_id,
         worker_id=args.worker_id if identity is None else None,
@@ -410,6 +433,62 @@ def _materialize_run(
     return prepare_agent_invocation(request)
 
 
+# 디스패치 composer 가 필수 자원 블록을 싣는 audience. 이 명령으로 먼저 발행된
+# 프롬프트는 디스패치가 그대로 쓰므로, 블록을 여기서 붙이지 않으면 워커에 닿지 않는다.
+_RESOURCE_AUDIENCES = frozenset({"implementation-executor", "implementation-verifier"})
+
+
+def _implementation_anchors(
+    project_root: Path, manifest_path: Path, worker_id: str,
+) -> list[str]:
+    """디스패치 composer 와 같은 구현 앵커 줄."""
+    try:
+        return implementation_anchor_lines(
+            project_root=project_root,
+            run_manifest_path=manifest_path,
+            runtime_root=_runtime_root(),
+            worker_id=worker_id,
+        )
+    except InitialPromptMaterializationError as exc:
+        raise AgentPromptCliError(f"implementation prompt anchors: {exc}") from exc
+
+
+def _runtime_root() -> Path:
+    from ...paths import find_asset_root
+
+    root = find_asset_root(("prompts", "profiles"), is_present=Path.is_dir)
+    if root is None:
+        raise AgentPromptCliError(
+            "prompt profiles not found: no prompts/profiles under OKSTRA_HOME "
+            "or this checkout"
+        )
+    return root
+
+
+def _with_required_resources(
+    project_root: Path, manifest_path: Path, worker_id: str, body: str,
+) -> str:
+    """리드의 지시문 뒤에 composer 와 같은 필수 자원 블록을 붙인다.
+
+    executor 의 BLOCKING 게이트 세 본문, verifier 의 `_implementation-verifier.md`
+    (self-mock 검출기 호출문 포함), clarification 권한 블록, fix-run carry 다.
+    배송 방식(eager / lazy)은 run 매니페스트의 선언을 따른다.
+    """
+    runtime_root = _runtime_root()
+    try:
+        block = required_resource_block(
+            project_root=project_root,
+            run_manifest_path=manifest_path,
+            runtime_root=runtime_root,
+            worker_id=worker_id,
+        )
+    except InitialPromptMaterializationError as exc:
+        raise AgentPromptCliError(f"required prompt resources: {exc}") from exc
+    if not block:
+        return body
+    return body.rstrip() + "\n\n" + block + "\n"
+
+
 def _complete_run_reverify_body(
     args: argparse.Namespace, manifest: Mapping[str, Any],
     active_context: Mapping[str, Any], assignment: AgentModelAssignment,
@@ -956,17 +1035,43 @@ def _snapshot_standalone_duties(destination: Path) -> None:
             "OKSTRA_HOME or this checkout"
         )
     source = root.joinpath(*duties_relative)
+    # 공통 계약은 직무가 아니라 `agents/` 가 소유한다(ADR-0017). 동결본은 한
+    # 뿌리여야 하므로 여기서 함께 싣는다.
+    common_root = find_asset_root(("agents", "common.json"), is_present=Path.is_file)
+    if common_root is None:
+        raise AgentPromptCliError(
+            "agent common contract not found: no agents/common.json under "
+            "OKSTRA_HOME or this checkout"
+        )
+    common_source = common_root / "agents" / "common.json"
+
+    def _staged_digest() -> str:
+        staged = Path(tempfile.mkdtemp(prefix=".okstra-standalone-duties."))
+        try:
+            shutil.copytree(source, staged, dirs_exist_ok=True)
+            shutil.copyfile(common_source, staged / "common.json")
+            shutil.copytree(
+                common_source.parent / "roles", staged / "roles", dirs_exist_ok=True
+            )
+            return digest_duty_catalog(staged)
+        finally:
+            shutil.rmtree(staged, ignore_errors=True)
+
     if destination.exists():
-        if not destination.is_dir() or digest_duty_catalog(destination) != digest_duty_catalog(source):
+        if not destination.is_dir() or digest_duty_catalog(destination) != _staged_digest():
             raise AgentPromptCliError("standalone duty snapshot conflicts with existing files")
         return
     temporary = Path(tempfile.mkdtemp(prefix=f".{destination.name}.", dir=destination.parent))
     try:
         shutil.copytree(source, temporary, dirs_exist_ok=True)
+        shutil.copyfile(common_source, temporary / "common.json")
+        shutil.copytree(
+            common_source.parent / "roles", temporary / "roles", dirs_exist_ok=True
+        )
         try:
             os.rename(temporary, destination)
         except FileExistsError:
-            if digest_duty_catalog(destination) != digest_duty_catalog(source):
+            if digest_duty_catalog(destination) != _staged_digest():
                 raise AgentPromptCliError("standalone duty snapshot publication conflict")
     finally:
         if temporary.exists():