okstra 0.202.0 → 0.205.0

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

@@ -0,0 +1,108 @@
+# Claude Code Worker Session Contract
+
+This file is the host contract for a worker running **inside** a Claude Code
+session (`runner=native-session`). The dispatch prompt names it as
+`**Host Session Contract Path:**`. It owns only what is true because the worker
+shares the lead's host session; the duty contract owns the role, the selected
+preamble owns the audience procedure, and the task instructions own this run's
+inputs and outputs. A `runner=cli-wrapper` worker runs as its own provider
+process and never receives this file.
+
+## Dispatch verification
+
+The summon message carried the absolute path of your dispatch prompt document,
+not the prompt itself. You have already read that document; these checks confirm
+you read the right one.
+
+1. Extract the absolute `Project Root` (a line starting with `**Project Root:**`
+   or `Project Root:`). If it is absent, return
+   `CLAUDE_PROJECT_ROOT_MISSING: absolute Project Root was not provided in the lead prompt`
+   and do nothing else.
+2. Check that the path you were summoned with matches the document's
+   `Assigned worker prompt history path:` header, resolving a relative header
+   value against `Project Root`. On a mismatch, return
+   `CLAUDE_PROMPT_PATH_MISSING: summon path does not match the document's assigned prompt history path`.
+   The lead persisted and verified that document before dispatch, so never
+   rewrite it.
+
+## Working directory and shell
+
+Anchor every file operation to the absolute `Project Root`. Use absolute paths;
+do not rely on inherited cwd, and never use `cd` to move the session.
+
+- **Executor exception (implementation runs).** When you are the `Executor` and
+  the prompt provides an `EXECUTOR_WORKTREE_PATH` that differs from the
+  session's cwd, prefix cwd-sensitive Bash commands (`cargo *`, `npm *`,
+  `pnpm *`, `bun *`, `pytest`, `make *`, `go *`, and other toolchain
+  build/test commands) with `cd <EXECUTOR_WORKTREE_PATH> && ` in the same Bash
+  invocation. Pass the chained command directly to the Bash tool; do not wrap it
+  in `bash -lc "..."` or `bash -c "..."`, because the leading `cd` token has to
+  stay visible to the permission layer. The `cd` is scoped to that one subshell
+  and does not move the session, which is why it does not contradict the rule
+  above.
+- **Verifier QA-gate exception.** A verifier may use the same
+  `cd <WORKTREE> && <cmd>` shape for the project-declared `qaCommands` (lint,
+  format, typecheck, test) from `project.json`, since those are cwd-sensitive by
+  nature. Outside the QA gate a verifier still reads by absolute path only.
+- **No chaining beyond `cd && cmd`.** The permission matcher allows exactly the
+  two-segment shape. Appending a pipe, semicolon, redirect, or second `&&` — for
+  example `cd ... && cargo test ... 2>&1 | tail -20; echo "exit:$?"` —
+  disqualifies the prefix match and raises a permission prompt on every
+  dispatch. Let the host capture stdout, stderr, and the exit code natively. If
+  you genuinely need less output, run the command and read the result in a
+  separate call.
+- **Commands must not be able to prompt.** Your Bash calls see the user's own
+  shell, where `cp`, `mv`, and `rm` are commonly aliased to their `-i` form. The
+  confirmation that alias raises has nobody to answer it, and the dispatch hangs
+  until it is killed. Invoke these as `command cp` / `command mv` /
+  `command rm`, which skips alias expansion. Do not reach for `-f` instead: it
+  also changes what the tool does on failure, and `rm -f` reports success on a
+  path that never existed.
+
+## MCP
+
+The run's available MCP servers and tools are listed in the analysis packet's
+`Available MCP Servers` section. When that section is absent or says none, treat
+MCP as unavailable for this run and never infer tools from host configuration.
+Call a listed tool directly by name (`mcp__<server>__<tool>`); do not shell out
+via `claude --mcp-cli call ...` and do not run a tool name as a Bash command.
+When a server you need is not listed, record `MCP not available for this run` in
+your output rather than guessing a tool name.
+
+## Post-write gates (implementation executor)
+
+An executor prompt carries two gate blocks the lead appends after the coding
+preflight: `Pre-commit diff review sweep` and `Implementation self-check`.
+Execute both and record their coverage lines exactly as the blocks specify. The
+provider wrappers refuse to launch an executor prompt that lacks them
+(`*_POSTWRITE_GATE_MISSING`); a worker in this session has no wrapper, so the
+contract lands on you. If either block is missing, record a typed `tool-failure`
+through `okstra error-log append-observed` and tell the lead to re-dispatch with
+the blocks included.
+
+## Returning
+
+The lead's dispatch returns as soon as the session is spawned and does not block
+on you. It detects completion by polling your result file, so that file's
+appearance at `**Result Path:**` is the only completion signal it has. Lingering
+after the file is on disk extends the phase's wall-clock time for the whole run.
+
+After the write succeeds:
+
+1. Return your final message immediately, beginning with your model identity as
+   the selected preamble specifies.
+2. Do not perform further `Read`, `Grep`, `Glob`, or MCP calls, and do not
+   re-review your own output.
+3. Do not rewrite the result file. If a correction is genuinely required, make a
+   single `Edit` and return.
+4. The one exception is recording a `tool-failure` when the failure happened
+   after the write; return immediately after that command.
+
+**Enforced:** `validators/validate-run.py` `validate_team_state` fails a run
+whose worker carries a terminal status with no saved result file at its assigned
+Result Path.
+
+If you catch yourself thinking "let me double-check section 3" after the write
+succeeded, stop. Convergence and the report writer reconcile gaps across all
+workers; extra depth in one worker at the cost of returning late is a net loss
+for the run.

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

@@ -205,6 +205,7 @@ The worker's `--sandbox danger-full-access` flag only selects the child Codex po
 - For convergence reverify, consume the persisted round plan exactly. This adapter may map and transport each returned batch, but it cannot change batch membership and does not classify findings or branch on task type, provider, or model identity.
 - Do not invoke Claude Code team or subagent tools.
 - The prepared run manifest and team-state are the dispatch authority. A `runner=native-session` assignment stays in the current Codex host; a `runner=cli-wrapper` assignment uses the registered provider wrapper. Unsupported explicitly requested workers fail; an adapter must not silently change the roster.
+- This host declares no worker session contract. A `runner=native-session` worker therefore receives no host session rules beyond its duty contract, the selected preamble, and the task instructions; the dispatch prompt carries no `**Host Session Contract Path:**` header. Declaring one means adding `workerSessionContract` to this adapter's `manifest.json` and descriptor — it is never installed into a host-global discovery path.
 - The report-writer follows its persisted provider, model, and runner assignment exactly. It has no Codex-only provider override or separate opt-in gate.
 - Reverify and critic retries invoke a fresh worker attempt and persist the core-supplied `dispatchKind` (`reverify-r<N>` or `critic`) in the dispatch record; never reuse a prior rollout as a new vote.
 - Native calls use only `hostModelValue`. Immediately before the host primitive, run `okstra agent-prompt record-dispatch` with the project root, run manifest, verified metadata path, and `--enforcement-mode host-native-spec-link-gate`; after the Result Path exists, run `okstra agent-prompt link-result` with `--dispatch-id <invocationId>:attempt-1` and that path before accepting it. CLI calls use only `modelExecutionValue` through `worker-dispatch`, which records its own dispatch. The native linkage proves association with a verified specification, not observed prompt delivery.

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

@@ -161,6 +161,8 @@ For a `host-text` mapping, render each numbered item as its option label followe
 | `record_lead_event` | Append progress and activity records to the manifest-provided `leadEventsPath`. Use `okstra lead-progress append --phase <phase-id>` for a checkpoint and `okstra agent-activity append --kind <kind>` for an activity record; both resolve the ledger path from the run manifest. Emit the matching `PROGRESS:` line — the command prints it as `progressLine` — and, when an activity record is required, the immediately following `ACTIVITY:` line from the same structured fields. |
 | `collect_usage` | Return explicit unavailable lead usage until Grok registers a session transcript or CLI usage artifact contract. |
 
+- This host declares no worker session contract. A `runner=native-session` worker therefore receives no host session rules beyond its duty contract, the selected preamble, and the task instructions; the dispatch prompt carries no `**Host Session Contract Path:**` header. Declaring one means adding `workerSessionContract` to this adapter's `manifest.json` and descriptor — it is never installed into a host-global discovery path.
+
 ## Completion, cleanup, and resume
 
 - Do not infer the current host from an installed `grok` executable. The runtime must come from an explicit request or current-session declaration.

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

@@ -83,6 +83,8 @@ Render every numbered item as its option label followed by its description verba
 | `record_lead_event` | Append progress and activity records to the manifest-provided `leadEventsPath`. Use `okstra lead-progress append --phase <phase-id>` for a checkpoint and `okstra agent-activity append --kind <kind>` for an activity record; both resolve the ledger path from the run manifest. Emit the matching `PROGRESS:` line — the command prints it as `progressLine` — and, when an activity record is required, the immediately following `ACTIVITY:` line from the same structured fields. |
 | `collect_usage` | Return explicit unavailable lead usage until Kimi registers a session transcript or CLI usage artifact contract. |
 
+- This host declares no worker session contract. A `runner=native-session` worker therefore receives no host session rules beyond its duty contract, the selected preamble, and the task instructions; the dispatch prompt carries no `**Host Session Contract Path:**` header. Declaring one means adding `workerSessionContract` to this adapter's `manifest.json` and descriptor — it is never installed into a host-global discovery path.
+
 ## Completion, cleanup, and resume
 
 - Do not infer the current host from an installed `kimi` executable. The runtime must come from an explicit request or current-session declaration.

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

@@ -33,9 +33,16 @@ ANTIGRAVITY = {
         "gemini-3.1-pro", "Gemini 3.1 Pro", "gemini-3.1-pro",
         aliases=("gemini 3.1 pro",),
     ),
+    "gemini-3.8-flash": ModelSpec(
+        "gemini-3.8-flash", "Gemini 3.8 Flash", "gemini-3.8-flash",
+        aliases=("gemini 3.8 flash",),
+    ),
+    # picker 에서는 감춘다: Flash 계열의 최신은 3.8 이다(`agy models` 2026-09-23
+    # 확인). 엔트리는 남긴다 — 이 모델로 디스패치된 과거 task 의 서빙 모델
+    # 관측값이 카탈로그에서 자기 행을 찾아야 게이트를 통과한다.
     "gemini-3.7-flash": ModelSpec(
         "gemini-3.7-flash", "Gemini 3.7 Flash", "gemini-3.7-flash",
-        aliases=("gemini 3.7 flash",),
+        aliases=("gemini 3.7 flash",), selectable=False,
     ),
 }
 

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

@@ -41,6 +41,14 @@ CLAUDE = {
         "opus-5", "opus-5", "claude-opus-5", aliases=("claude-opus-5",),
         channel_family="opus", selectable=False,
     ),
+    # opus 채널이 지금 서빙하는 점-릴리스. 엔트리가 없으면 served-model 게이트가
+    # 관측값을 카탈로그에서 못 찾아 dispatch 가 exit 78 로 실패한다 — 실측
+    # 2026-09-23, 두 프로젝트에서 `claude-opus-5-5` 로 같은 실패(dev-10860
+    # stage-3·4·5). haiku-4-5-20251001 과 같은 이유의 엔트리다.
+    "opus-5-5": ModelSpec(
+        "opus-5-5", "opus-5-5", "claude-opus-5-5", aliases=("claude-opus-5-5",),
+        channel_family="opus", selectable=False,
+    ),
     "sonnet": ModelSpec(
         "sonnet", "sonnet", "sonnet", version_kind="channel", channel_family="sonnet"
     ),

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

@@ -17,9 +17,21 @@ import okstra_ctl.model_discovery as model_discovery
 
 
 # 모델 식별자와 순서는 Codex의 `~/.codex/models_cache.json`을 따른다
-# (2026-09-07 확인, 클라이언트 0.153.4): astra / sol / terra / luna.
-# `gpt-5.6` is not a slug that catalog offers at all, so it is gone from here;
-# its rate moved to `_LEGACY_CODEX_PRICING` so past runs still price.
+# (2026-09-23 확인, 클라이언트 0.155.0): gpt-6 astra / sol / luna 와 5.6 계열의
+# sol / terra / luna. `gpt-5.6` is not a slug that catalog offers at all, so it
+# is gone from here; its rate moved to `_LEGACY_CODEX_PRICING` so past runs
+# still price.
+#
+# 노출 규칙: 티어(astra·sol·terra·luna)마다, **이 계정이 실제로 서빙하는** 최신
+# 세대 하나만 selectable 로 둔다. 카탈로그가 슬러그를 내놓는 것과 계정이 그것을
+# 실행하는 것은 다르다 — 실측 2026-09-23(jobs dev-10860
+# implementation-option-selection-002): ChatGPT 계정으로 로그인한 이 기계에서
+# `gpt-6-sol` 디스패치가 두 번 다 400 으로 거절됐다
+# ("The 'gpt-6-sol' model is not supported when using Codex with a ChatGPT
+# account"). 같은 계정의 `models_cache.json` 도 6세대로는 astra 만 싣는다.
+# 그래서 sol·luna 티어는 5.6 행이 선택 가능한 행이고, gpt-6 의 두 행은 엔트리만
+# 남긴다 — 서빙하는 계정이 그 값을 쓰거나 과거 run 을 정산할 때 필요하다.
+# astra 는 이 계정에서 실제로 돌아 gpt-6 행이 선택 가능하다.
 CODEX = {
     # 비용은 계정이 구독이든 API 든 공개 API 단가(입력·캐시 입력·출력 USD/1M)로
     # 추정한다 — 리포트가 답하는 것은 "얼마나 썼는가" 이지 "청구서에 얼마가
@@ -28,12 +40,17 @@ CODEX = {
     # 계상된다(실측 2026-09-08). 출처: OpenAI 표준 등급, 2026-09 기준
     # (morphllm.com/openai-api-pricing, cloudzero.com/blog/openai-pricing,
     # layer3labs.io/guides/gpt-6-astra-api-pricing).
+    # gpt-6 단가는 OpenAI 모델 문서의 표준 등급(2026-09-23 확인):
+    # developers.openai.com/api/docs/models/gpt-6-sol, .../gpt-6-luna.
     "gpt-6-astra": ModelSpec("gpt-6-astra", "gpt-6-astra", "gpt-6-astra", pricing=(10.0, 1.0, 50.0)),
-    "gpt-5.6-sol": ModelSpec("gpt-5.6-sol", "gpt-5.6-sol", "gpt-5.6-sol", pricing=(5.0, 0.50, 30.0)),
+    # picker 에서는 감춘다: 이 계정이 400 으로 거절한다(위 노출 규칙). 엔트리는
+    # 남긴다 — 서빙하는 계정의 값이고, 과거 run 의 단가도 이 표에서 찾는다.
+    "gpt-6-sol": ModelSpec("gpt-6-sol", "gpt-6-sol", "gpt-6-sol", pricing=(2.0, 0.20, 10.0), selectable=False),
+    "gpt-6-luna": ModelSpec("gpt-6-luna", "gpt-6-luna", "gpt-6-luna", pricing=(0.10, 0.01, 0.50), selectable=False),
     "gpt-5.6-terra": ModelSpec("gpt-5.6-terra", "gpt-5.6-terra", "gpt-5.6-terra", pricing=(2.0, 0.20, 12.0)),
+    "gpt-5.6-sol": ModelSpec("gpt-5.6-sol", "gpt-5.6-sol", "gpt-5.6-sol", pricing=(5.0, 0.50, 30.0)),
     "gpt-5.6-luna": ModelSpec("gpt-5.6-luna", "gpt-5.6-luna", "gpt-5.6-luna", pricing=(0.20, 0.02, 1.20)),
-    # picker 에서는 감춘다. 엔트리는 남긴다 — 과거 run 의 토큰 사용량을
-    # 정산할 때 pricing 을 이 표에서 찾는다.
+    # picker 에서는 감춘다(사유는 위와 동일 — 더 이상 카탈로그가 내놓지 않는다).
     "gpt-5.4-mini": ModelSpec("gpt-5.4-mini", "gpt-5.4-mini", "gpt-5.4-mini", pricing=(0.75, 0.075, 4.50), selectable=False),
     "codex-auto-review": ModelSpec("codex-auto-review", "codex-auto-review", "codex-auto-review", selectable=False),
 }

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

@@ -21,7 +21,11 @@ from okstra_ctl.domain.worker_stream import StreamEvent, Text, ToolCall, ToolRes
 
 
 GROK = {
-    "grok-4.6": ModelSpec("grok-4.6", "grok-4.6", "grok-4.6", pricing=(2.00, 0.50, 6.00)),
+    "grok-4.7": ModelSpec("grok-4.7", "grok-4.7", "grok-4.7", pricing=(2.00, 0.50, 6.00)),
+    # picker 에서는 감춘다: grok-4.7 이 같은 계열의 최신이다(`grok` CLI 1.0.40 의
+    # 기본값도 4.7, 2026-09-23 확인). 엔트리는 남긴다 — 과거 run 의 정산이 이
+    # 표의 단가를 읽고, 서빙 모델 게이트가 옛 관측값을 여기서 찾는다.
+    "grok-4.6": ModelSpec("grok-4.6", "grok-4.6", "grok-4.6", pricing=(2.00, 0.50, 6.00), selectable=False),
     # picker 에서는 감춘다(사유는 codex 의 gpt-5.4-mini 와 동일).
     "grok-build-0.1": ModelSpec("grok-build-0.1", "grok-build-0.1", "grok-build-0.1", pricing=(1.00, 0.20, 2.00), selectable=False),
 }
@@ -294,7 +298,7 @@ def create_provider() -> ProviderSpec:
         display_label="Grok",
         models=GROK,
         default_models={
-            role: "grok-4.6"
+            role: "grok-4.7"
             for role in (
                 "lead",
                 "analyser",

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