okstra 0.220.0 → 0.221.0

package/runtime/python/okstra_ctl/mcp_servers.py

@@ -0,0 +1,421 @@
+"""프로젝트 MCP 서버 선언과 provider 별 도달성 판정.
+
+선언은 논리 서버 이름과, provider CLI 가 그 서버를 나열하는 이름(`aliases`)만
+갖는다. 어느 provider 가 볼 수 있는지는 각 어댑터의 `mcp_inventory` 가 답하며,
+이 모듈은 provider 이름을 하나도 모른다.
+"""
+from __future__ import annotations
+
+import re
+import subprocess
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from okstra_project.dirs import OKSTRA_DIR_NAME, project_json_path
+
+from .domain.mcp import McpInventory, McpInventoryProbe
+from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
+
+PROBE_TIMEOUT_SECONDS = 20.0
+
+Reachability = Literal["reachable", "disabled", "missing", "unknown"]
+
+
+class McpDeclarationError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class McpServerDeclaration:
+    name: str
+    description: str
+    tools: tuple[str, ...]
+    aliases: tuple[str, ...] = ()
+    notes: str = ""
+
+    def to_json(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "name": self.name,
+            "description": self.description,
+            "tools": list(self.tools),
+        }
+        if self.aliases:
+            payload["aliases"] = list(self.aliases)
+        if self.notes:
+            payload["notes"] = self.notes
+        return payload
+
+
+@dataclass(frozen=True)
+class ProviderCell:
+    provider_id: str
+    status: Reachability
+    visible_name: str = ""
+    note: str = ""
+
+
+@dataclass(frozen=True)
+class ServerReachability:
+    server: McpServerDeclaration
+    cells: tuple[ProviderCell, ...]
+
+    def reachable_from(self) -> tuple[str, ...]:
+        return tuple(c.provider_id for c in self.cells if c.status == "reachable")
+
+
+def _string_list(value: object, field: str, errors: list[str]) -> tuple[str, ...]:
+    if not isinstance(value, list) or not all(
+        isinstance(item, str) and item.strip() for item in value
+    ):
+        errors.append(f"`{field}` must be a list of non-empty strings")
+        return ()
+    return tuple(item.strip() for item in value)
+
+
+def parse_declaration(raw: object) -> tuple[McpServerDeclaration | None, list[str]]:
+    if not isinstance(raw, dict):
+        return None, ["entry must be an object"]
+    errors: list[str] = []
+    name = raw.get("name")
+    if not isinstance(name, str) or not name.strip():
+        errors.append("`name` must be a non-empty string")
+    description = raw.get("description")
+    if not isinstance(description, str) or not description.strip():
+        errors.append("`description` must be a non-empty string")
+    tools = _string_list(raw.get("tools"), "tools", errors)
+    if raw.get("tools") == []:
+        errors.append("`tools` must not be empty")
+    aliases = _string_list(raw["aliases"], "aliases", errors) if "aliases" in raw else ()
+    notes = raw.get("notes", "")
+    if not isinstance(notes, str):
+        errors.append("`notes` must be a string")
+    if errors:
+        return None, errors
+    return (
+        McpServerDeclaration(
+            name=name.strip(),
+            description=description.strip(),
+            tools=tools,
+            aliases=aliases,
+            notes=notes.strip(),
+        ),
+        [],
+    )
+
+
+def load_declarations(
+    project_root: Path,
+) -> tuple[tuple[McpServerDeclaration, ...], tuple[str, ...]]:
+    path = project_json_path(project_root)
+    if not path.is_file():
+        return (), ()
+    try:
+        raw = load_owned_object(path, artifact="project config")
+    except JsonBoundaryError as exc:
+        return (), (str(exc),)
+    servers = raw.get("mcpServers")
+    if servers is None:
+        return (), ()
+    if not isinstance(servers, list):
+        return (), (f"`mcpServers` in {path} must be a list",)
+    declarations: list[McpServerDeclaration] = []
+    problems: list[str] = []
+    seen: set[str] = set()
+    for index, entry in enumerate(servers):
+        declaration, errors = parse_declaration(entry)
+        if declaration is None:
+            problems.append(f"mcpServers[{index}]: " + "; ".join(errors))
+            continue
+        if declaration.name in seen:
+            problems.append(f"mcpServers[{index}]: duplicate name `{declaration.name}`")
+            continue
+        seen.add(declaration.name)
+        declarations.append(declaration)
+    return tuple(declarations), tuple(problems)
+
+
+def _read_project_config(project_root: Path) -> tuple[Path, dict[str, Any]]:
+    path = project_json_path(project_root)
+    if not path.is_file():
+        raise McpDeclarationError(
+            f"{path} not found; register the project with `okstra setup` first"
+        )
+    return path, load_owned_object(path, artifact="project config")
+
+
+def upsert_declaration(project_root: Path, declaration: McpServerDeclaration) -> bool:
+    path, data = _read_project_config(project_root)
+    servers = data.get("mcpServers") or []
+    if not isinstance(servers, list):
+        raise McpDeclarationError(f"`mcpServers` in {path} must be a list")
+    kept = [
+        entry for entry in servers
+        if not (isinstance(entry, dict) and entry.get("name") == declaration.name)
+    ]
+    replaced = len(kept) != len(servers)
+    data["mcpServers"] = [*kept, declaration.to_json()]
+    write_owned_object_atomic(path, data, artifact="project config")
+    return replaced
+
+
+def remove_declaration(project_root: Path, name: str) -> bool:
+    path, data = _read_project_config(project_root)
+    servers = data.get("mcpServers") or []
+    if not isinstance(servers, list):
+        raise McpDeclarationError(f"`mcpServers` in {path} must be a list")
+    kept = [
+        entry for entry in servers
+        if not (isinstance(entry, dict) and entry.get("name") == name)
+    ]
+    if len(kept) == len(servers):
+        return False
+    data["mcpServers"] = kept
+    write_owned_object_atomic(path, data, artifact="project config")
+    return True
+
+
+def normalize_server_name(name: str) -> str:
+    return re.sub(r"[\s._-]+", "", name).lower()
+
+
+def _match(
+    declaration: McpServerDeclaration, inventory: McpInventory,
+) -> tuple[Reachability, str]:
+    if not inventory.listed:
+        return "unknown", ""
+    wanted = {normalize_server_name(n) for n in (declaration.name, *declaration.aliases)}
+    found = [s for s in inventory.servers if normalize_server_name(s.name) in wanted]
+    for server in found:
+        if server.state == "enabled":
+            return "reachable", server.name
+    if found:
+        return "disabled", found[0].name
+    return "missing", ""
+
+
+@dataclass(frozen=True)
+class CommandOutcome:
+    stdout: str | None
+    failure: str = ""
+
+
+CommandRunner = Callable[[tuple[str, ...], Path], CommandOutcome]
+
+
+def run_command(argv: tuple[str, ...], project_root: Path) -> CommandOutcome:
+    command = " ".join(argv)
+    try:
+        completed = subprocess.run(
+            list(argv),
+            cwd=project_root,
+            capture_output=True,
+            text=True,
+            timeout=PROBE_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except FileNotFoundError:
+        return CommandOutcome(None, f"`{argv[0]}` is not installed")
+    except subprocess.TimeoutExpired:
+        return CommandOutcome(None, f"`{command}` timed out after {PROBE_TIMEOUT_SECONDS:.0f}s")
+    except OSError as exc:
+        return CommandOutcome(None, f"`{command}` failed to start ({exc})")
+    if completed.returncode != 0:
+        return CommandOutcome(None, f"`{command}` exited {completed.returncode}")
+    return CommandOutcome(completed.stdout)
+
+
+def probe_inventories(
+    probes: Mapping[str, McpInventoryProbe | None],
+    project_root: Path,
+    runner: CommandRunner | None = None,
+) -> dict[str, McpInventory]:
+    """같은 명령은 한 번만 실행한다. claude 와 zai 처럼 CLI 를 공유하는 어댑터가
+    목록 비용(실측 7.5초)을 두 번 치르지 않게 하려는 것이다."""
+    commands = {probe.argv for probe in probes.values() if probe is not None}
+    outcomes: dict[tuple[str, ...], CommandOutcome] = {}
+    if commands:
+        with ThreadPoolExecutor(max_workers=len(commands)) as pool:
+            futures = {
+                argv: pool.submit(runner or run_command, argv, project_root)
+                for argv in commands
+            }
+            outcomes = {argv: future.result() for argv, future in futures.items()}
+    inventories: dict[str, McpInventory] = {}
+    for provider_id, probe in probes.items():
+        if probe is None:
+            inventories[provider_id] = McpInventory.unavailable(
+                "adapter declares no MCP inventory probe"
+            )
+            continue
+        outcome = outcomes[probe.argv]
+        inventories[provider_id] = (
+            probe.parse(outcome.stdout)
+            if outcome.stdout is not None
+            else McpInventory.unavailable(outcome.failure)
+        )
+    return inventories
+
+
+def assess(
+    declarations: Sequence[McpServerDeclaration],
+    inventories: Mapping[str, McpInventory],
+) -> tuple[ServerReachability, ...]:
+    rows: list[ServerReachability] = []
+    for declaration in declarations:
+        cells = []
+        for provider_id, inventory in inventories.items():
+            status, visible = _match(declaration, inventory)
+            cells.append(ProviderCell(provider_id, status, visible, inventory.note))
+        rows.append(ServerReachability(declaration, tuple(cells)))
+    return tuple(rows)
+
+
+def provider_probes(provider_ids: Iterable[str]) -> dict[str, McpInventoryProbe | None]:
+    from .registry.provider_registry import default_provider_registry
+
+    registry = default_provider_registry()
+    return {
+        provider_id: registry.resolve(provider_id).mcp_inventory
+        for provider_id in dict.fromkeys(provider_ids)
+    }
+
+
+def _cell_text(cell: ProviderCell) -> str:
+    if cell.status == "reachable":
+        return f"{cell.provider_id} (as `{cell.visible_name}`)"
+    if cell.status == "disabled":
+        return f"{cell.provider_id} (disabled as `{cell.visible_name}`)"
+    return f"{cell.provider_id} ({cell.status})"
+
+
+def reachability_sentence(row: ServerReachability) -> str:
+    reachable = [c for c in row.cells if c.status == "reachable"]
+    other = [c for c in row.cells if c.status != "reachable"]
+    parts = []
+    if reachable:
+        parts.append("Reachable from: " + ", ".join(_cell_text(c) for c in reachable))
+    if other:
+        parts.append("Not reachable: " + ", ".join(_cell_text(c) for c in other))
+    return ". ".join(parts)
+
+
+def reachability_warnings(rows: Sequence[ServerReachability]) -> tuple[str, ...]:
+    warnings = []
+    for row in rows:
+        for cell in row.cells:
+            if cell.status == "reachable":
+                continue
+            detail = _cell_text(cell)
+            if cell.note:
+                detail += f": {cell.note}"
+            warnings.append(
+                f"mcp: server `{row.server.name}` is not reachable from provider {detail}"
+            )
+    return tuple(warnings)
+
+
+NO_MCP_SERVERS_LINE = (
+    f"- No MCP servers are declared in `{OKSTRA_DIR_NAME}/project.json`'s "
+    "`mcpServers` array. Treat MCP tools as unavailable for this run. To enable "
+    "them, register each server with `okstra mcp add` and re-render the bundle."
+)
+
+
+def render_block(
+    declarations: Sequence[McpServerDeclaration],
+    rows: Sequence[ServerReachability] = (),
+) -> str:
+    """툴 이름은 논리 이름으로만 싣는다. 실제 호출 이름은 CLI 마다 규칙이 달라
+    워커가 자기 CLI 의 툴 목록에서 찾는다."""
+    if not declarations:
+        return NO_MCP_SERVERS_LINE
+    by_name = {row.server.name: row for row in rows}
+    lines = []
+    for declaration in declarations:
+        parts = [f"`{declaration.name}`"]
+        if declaration.aliases:
+            parts[0] += " (also listed as " + ", ".join(
+                f"`{alias}`" for alias in declaration.aliases
+            ) + ")"
+        parts.append(declaration.description)
+        parts.append("Tools: " + ", ".join(f"`{tool}`" for tool in declaration.tools))
+        if declaration.notes:
+            parts.append(declaration.notes)
+        row = by_name.get(declaration.name)
+        if row is not None and row.cells:
+            parts.append(reachability_sentence(row))
+        lines.append("- " + ". ".join(p.rstrip(".") for p in parts) + ".")
+    return "\n".join(lines)
+
+
+@dataclass(frozen=True)
+class BriefSource:
+    label: str
+    pattern: re.Pattern[str]
+    keyword: str
+
+
+BRIEF_SOURCES = (
+    BriefSource(
+        "Figma",
+        re.compile(r"figma\.com/(?:file|design|proto|board)/", re.IGNORECASE),
+        "figma",
+    ),
+)
+
+
+def brief_source_warnings(
+    brief_text: str,
+    declarations: Sequence[McpServerDeclaration],
+    rows: Sequence[ServerReachability] = (),
+) -> tuple[str, ...]:
+    warnings = []
+    for source in BRIEF_SOURCES:
+        if not source.pattern.search(brief_text):
+            continue
+        matching = [
+            d for d in declarations
+            if any(source.keyword in normalize_server_name(n) for n in (d.name, *d.aliases))
+        ]
+        if not matching:
+            warnings.append(
+                f"mcp: brief cites a {source.label} URL but no mcpServers entry matches "
+                f"'{source.keyword}'; register it with `okstra mcp add`"
+            )
+            continue
+        names = {d.name for d in matching}
+        checked = [row for row in rows if row.server.name in names]
+        if checked and not any(row.reachable_from() for row in checked):
+            warnings.append(
+                f"mcp: brief cites a {source.label} URL but no selected provider can "
+                f"reach {', '.join(sorted(names))}; add it to a provider CLI's MCP "
+                "configuration or select a provider that lists it"
+            )
+    return tuple(warnings)
+
+
+@dataclass(frozen=True)
+class PreparedMcp:
+    block: str
+    warnings: tuple[str, ...]
+
+
+def prepare_mcp(
+    project_root: Path,
+    provider_ids: Iterable[str],
+    brief_text: str,
+    runner: CommandRunner | None = None,
+) -> PreparedMcp:
+    """판정 결과는 경고와 렌더에만 쓰고 run 을 거절하지 않는다."""
+    declarations, problems = load_declarations(project_root)
+    warnings = [f"mcp: {problem}" for problem in problems]
+    rows: tuple[ServerReachability, ...] = ()
+    if declarations:
+        inventories = probe_inventories(provider_probes(provider_ids), project_root, runner)
+        rows = assess(declarations, inventories)
+        warnings.extend(reachability_warnings(rows))
+    warnings.extend(brief_source_warnings(brief_text, declarations, rows))
+    return PreparedMcp(render_block(declarations, rows), tuple(warnings))

package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md

@@ -77,7 +77,7 @@ When the synthesised verdict is `FAIL` and the lead minor fix does not apply, th
 **Entry.** Every blocking finding of the round meets all of these, or the run ends `FAIL` as before:
 
 1. A verifier cited where it is (`path:line`) and what the correct result is.
-2. The fix stays inside this stage's `plannedPaths` or files the executor already changed.
+2. The fix stays inside this stage's `plannedPaths` or files the executor already changed. A `FILE-SIZE:` finding also allows the new files the split creates beside the oversized one, so it always meets this rule.
 3. It needs no new plan step, dependency, schema, migration, or config of record — a finding that does is a plan change: end the run `FAIL` and route by `prompts/lead/phase-routing.md`.
 
 Changing a test's expected value is allowed here when the finding shows the oracle is wrong, because the verifiers re-verify the fix.
@@ -85,12 +85,13 @@ Changing a test's expected value is allowed here when the finding shows the orac
 **Procedure for round `<N>`.**
 
 1. Record the stage HEAD as `<base>` (`git rev-parse HEAD` in the stage worktree).
-2. Write the executor instruction with `okstra correction prompt --run-manifest <path> --round <N> --role executor --base <base> --finding <F-id> [--finding <F-id> ...]` into a file under the run's `state/`, then materialize it with `okstra agent-prompt materialize` — `--audience implementation-executor`, `--assignment-ref initial/<executor worker id>`, `--dispatch-kind correction-r<N>`, a new `--invocation-id` ending `-correction-r<N>-<executor worker id>`, and a result path `<executor worker id>-worker-correction-r<N>-implementation-<seq>.md`. Build a jobs file with `okstra agent-prompt jobs --dispatch-kind correction-r<N>`, dispatch it alone with `okstra team dispatch --jobs-file <path> --dispatch-kind correction-r<N>`, and settle it with `okstra team await`.
+2. Write the executor instruction with `okstra correction prompt --run-manifest <path> --round <N> --role executor --base <base> --stage-base <stage base> --finding <F-id> [--finding <F-id> ...]` into a file under the run's `state/`, then materialize it with `okstra agent-prompt materialize` — `--audience implementation-executor`, `--assignment-ref initial/<executor worker id>`, `--dispatch-kind correction-r<N>`, a new `--invocation-id` ending `-correction-r<N>-<executor worker id>`, and a result path `<executor worker id>-worker-correction-r<N>-implementation-<seq>.md`. Build a jobs file with `okstra agent-prompt jobs --dispatch-kind correction-r<N>`, dispatch it alone with `okstra team dispatch --jobs-file <path> --dispatch-kind correction-r<N>`, and settle it with `okstra team await`.
+   `--stage-base` (the carry's `stageCommitRange.base`) adds a `FILE-SIZE:<path>` finding for each file the stage diff leaves over the 400-line limit, computed by `okstra correction file-size`; a `FILE-SIZE-ADVISORY:` line (the 300-line target) never opens or joins a round; a round may hold only those findings, and `findingIds` records them by that id. Leave out a convergence finding id that restates a `FILE-SIZE:` line, or the executor reads it twice.
 3. Do the same for every verifier with `--role verifier`, `--audience implementation-verifier`, its own `initial/<verifier worker id>` assignment, and result `<verifier worker id>-worker-correction-r<N>-implementation-<seq>.md`; dispatch the verifiers in one batch without the executor.
 4. Converge the re-verification results the way the initial round was converged, restarting Phase 5.5 with `okstra convergence seed ... --restart-from-round0`.
 5. No re-verification verdict is `FAIL`: the round `result` is `pass` and the run continues to persistence with the post-fix head. Otherwise `result: fail`; start round `<N+1>` if the cap allows and the entry rules still hold, or end the run `FAIL`.
 
-**Enforced:** `scripts/okstra_ctl/dispatch_core.py` `_validate_correction_rounds` (via `correction_round.validate_correction_dispatch`) refuses a round past the cap, a verifier dispatch before that round's executor returned an `ok` result, a second executor fix in the same round, and round `<N+1>` before round `<N>` was re-verified. `validators/validate-run.py` `_validate_correction_rounds` (blocking) fails a report whose `correctionRounds` differ from the correction rounds the run dispatched, whose rounds are not 1, 2 in order, whose `result` contradicts its verdicts, or whose `verifierResults` are not the last round's verdicts. The entry rules are instructions only.
+**Enforced:** `scripts/okstra_ctl/dispatch_core.py` `_validate_correction_rounds` (via `correction_round.validate_correction_dispatch`) refuses a round past the cap, a verifier dispatch before that round's executor returned an `ok` result, a second executor fix in the same round, and round `<N+1>` before round `<N>` was re-verified. `validators/validate-run.py` `_validate_correction_rounds` (blocking) fails a report whose `correctionRounds` differ from the correction rounds the run dispatched, whose rounds are not 1, 2 in order, whose `result` contradicts its verdicts, or whose `verifierResults` are not the last round's verdicts. The entry rules are instructions only. `okstra stage-done` (`scripts/okstra_ctl/stage_done.py` `_check_file_size`) refuses to settle a stage whose carry range breaks the 400-line file-size limit and names the `--stage-base` to pass, so a size violation no verifier reported still reaches a correction round, or ends the run `FAIL` when no round is left.
 
 ## Self-review pass before finalising the report (the Okstra lead runs this; do not delegate it)
 

package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md

@@ -92,6 +92,7 @@ template's check; that template is gone.
   The file MUST NOT exist before the run starts (overwrite is refused — see `--force-stage` non-goal). **Enforced:** `validators/validate-run.py` `_validate_stage_carry_sidecar_exists` fails a run that declares `stageSidecarEvidence` without the file on disk. Transcribing the JSON into the report is not the same as writing it: `consumers` treats the carry file as the source of truth for marking the stage `done`, so a missing file leaves the stage permanently incomplete and blocks every dependent stage with a `PrepareError` — while this run reports success.
 - **Verifier gates are not yours to run (BLOCKING).** The self-mock detector (`validators/detect_self_mock.py`) belongs to the implementation verifier and is never delegated to you (`_implementation-verifier.md` §"Self-mock detection"). The coding-conventions preflight names it as the enforcement behind the no-self-mocking principle — that names who will check your diff, not a command for you to run. You MUST NOT invoke it and MUST NOT write `<task_root>/qa/self-mock-*.json`; running it early does not pre-satisfy the gate, because the verifier runs it again under its own duty. **Enforced:** that sidecar is not among the paths your attempt's `writePolicy.artifactPolicy.allowedPaths` carries, so the write audit closes the attempt as `error` with `artifact-root change exceeds batch policy union` (`scripts/okstra_ctl/execution_mutation_audit.py`) — a stage whose every gate passed still lands as a failed run. The same holds for the conformance results `<task_root>/qa/result-*.json`: you may run a conformance script to check your work — a baseline capture or `--compare` target goes under `<task_root>/qa/baseline/` and anything else it writes (build logs, measurements) under `<task_root>/qa/output/`, the only qa directories besides `qa/scripts/` your attempt may write — but the verifier records every result, including an earlier stage's result that your rewrite of its script made stale. When the approved plan tells you to write one, leave it and name it in your result as a plan step the verifier owns.
 - **An external Tier 3 non-PASS does NOT withhold the carry evidence.** A Tier 3 entry whose `requires` include `http`, `external`, or `db` is advisory. Its FAIL, MISSING, no result, startup failure, or credential / network / service absence gets recorded honestly — exact command, exit code, output tail, marked `ADVISORY` in `Validation evidence` — and you emit the carry evidence anyway. Only Tier 1 and Tier 2 failures withhold it. Withholding on an external result is what actually blocks the stage: the carry file is the only thing that can mark a stage `done`, the verifier re-runs that same command from the host (where a call your sandbox could not complete often passes), and a stage the verifier then PASSes can never be closed because its evidence was never written.
+- **File size: aim for 300 lines, never exceed 400 (BLOCKING at 400).** Each threshold is broken the same three ways — a new file over it, an existing file taken past it, a file already over it that grows by any net line — counted in physical lines. Breaking 400 is a blocking finding; breaking only 300 is an advisory recommendation the verifiers record. Put a new responsibility — a group of functions, a class, a `describe` block — in a new module or test file beside the existing one instead of appending, and when a file would pass 400, split it by responsibility; never compress code or drop comments to meet the number. Lockfiles, data (JSON / YAML), Markdown, fixtures, snapshots, generated and vendored files are exempt, as are languages okstra has no coding preflight for. Check with `okstra correction file-size --base <stage-base>` before you emit the carry evidence; it writes nothing, so you may run it. **Enforced:** every verifier runs the same command and reports each `FILE-SIZE:` line (400) as a blocking finding and each `FILE-SIZE-ADVISORY:` line (300) as a recommendation, and `okstra stage-done` (`scripts/okstra_ctl/stage_done.py` `_check_file_size`) refuses to settle a stage whose carry range still breaks 400, so the stage goes to a correction round.
 - **Reverse link (BLOCKING).** The runtime already appended a `status:"started"` row for this stage before the run began. The terminal row belongs to the lead's post-stage persistence and is verdict-gated — `status:"done"` with `carry_path` on a non-`FAIL` verdict, `status:"failed"` on `FAIL` (`_implementation-deliverable.md` §"Lead post-stage persistence").
 - **No PR / push in this phase.** This run produces local commits, carry sidecar evidence, verifier results, and the implementation final report only. Push and PR creation belong exclusively to the later `release-handoff` phase after `final-verification` returns `accepted`.
 

package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md

@@ -17,6 +17,7 @@ fails, fix it or surface the violation — do not claim done on a failing item.
 
 - diff-review done: the `Pre-commit diff review sweep` ran over the full diff and its `Coverage:` footer is in your audit sidecar — every changed file named, with each applied rule set carrying its outcome (`clean` or `fixed <n>`). No footer, or entries with no outcome → the sweep is unfinished; do not claim done.
 - functions: every new/edited function ≤50 effective lines, single purpose — cite the longest function's actual line count, not "all under 50"
+- file size: no source or test file this diff adds or grows ends over 400 physical lines, and no file already over 400 grew — paste the output of `okstra correction file-size --base <stage-base>`; it must end `QA-RESULT: PASS`. Aim for 300: for each `FILE-SIZE-ADVISORY:` line it prints, split the file or say why not. A responsibility that would push a file over goes into its own new module or test file
 - conventions: applied the routed pack + project patterns (name which ones)
 - names & comments: names say what, comments say why; no obvious-restatement comments; no truthful-name violations
 - verification: ran the actual build/test — paste the exact command line and its real exit code / output tail, never a paraphrased "tests pass"

package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md

@@ -214,13 +214,14 @@ Re-running commands proves the diff *builds and passes*; it does NOT prove the d
   - **Non-separating test data:** two scenarios whose setup values and assertions are identical, so a wrong implementation passes both; or new test tooling added in this diff (mock, state setter, repository branch) that no test calls.
   - **Effect claimed under its own mock:** a test presented as covering an effect whose producing path is replaced by a mock inside that same test. The mock's presence in the harness is not evidence the branch behind it works.
   - **Single-caller abstraction (KISS):** an abstraction layer this diff introduces — a helper module, a strategy / factory / builder, an indirection or wrapper layer, an interface or abstract base — that has exactly one caller after the change, where inlining it at that call site would be simpler. The rule is `overview.md` core principle 2: name the second caller now, or inline. Four exits are legitimate and each must **cite its evidence**: the approved plan declares it (a `testSeams[]` boundary or a variation-point extraction — cite the plan step); the project declares `architecture.style = hexagonal` and this is a port at the domain boundary (a port with one adapter is the normal shape, not a violation); it breaks a real import cycle (name both modules); or its single caller is the public API of a published package. Absent one of those, cite `path:line` and recommend the inlined shape. Do NOT raise this on a function extracted purely to bring a body under the 50-line cap — that is principle 5 doing its job — nor on a pre-existing abstraction this diff merely edits.
+  - **File-size limit (every verifier, not only the stage QA owner):** run `okstra correction file-size --base <base>` from the worktree cwd and log it in the `Read-only command log`. Each `FILE-SIZE:<path>:401 <before>-><after>` line it prints is a blocking finding cited exactly as printed — a new file over 400 lines, a file the diff took past 400, or a file already over 400 the diff grew. Recommended fix: move whole responsibilities into new modules or test files beside it. The command writes nothing and its result is the same for every verifier, so the finding converges and the lead sends it to a correction round. Each `FILE-SIZE-ADVISORY:<path>:301` line (the 300-line target, same three conditions) goes under the advisory findings below, not here. Do not judge size yourself: a file it does not print is not a finding (lockfiles, data, Markdown, fixtures, snapshots, generated files and languages without a coding preflight are exempt by `scripts/okstra_ctl/file_size_cap.py` `capped_path`).
   - **Caller-less identifier (YAGNI / orphan):** an identifier this diff leaves with zero callers — either newly added and never called (a speculative parameter, an optional config object, a "future-proof" hook, an exported helper whose only caller is hypothetical), or pre-existing code orphaned because this diff removed its last caller. Grep the identifier across the whole repository rather than the diff alone; a hit inside its own declaration, its own test, or a commented-out line is not a caller. Two exits are legitimate and must be **stated with their evidence**, never assumed: an identifier the approved plan reserves for a named later stage (cite the plan step), and a contract point something other than project code calls (a framework entrypoint, an implemented interface method, a migration hook, the public API of a published package — cite the caller or the registration). Anything else is work no requirement asked for: recommend deleting it, or folding an added parameter back into its single call site. A caller-less identifier is the one YAGNI violation that survives a green pipeline unchanged, which is why it grades here rather than as a recommendation.
-- **Advisory findings (recorded as recommendations; verdict MAY still PASS):** function >50 effective lines, a single body mixing read+write stages, weak readability, a missing-but-non-critical outcome assertion, weak-but-not-misleading names, priority-between-inputs policy inlined in a service condition instead of a named domain function, an error message asserting a cause the code never observed, a memory / concurrency / batching change with no test pinning the bound it claims, or (hexagonal overlay only) a service dependency this diff adds or modifies that injects a concrete adapter instead of a port — record it with the port sketch; advisory only while the project has not declared `architecture.style = hexagonal`, since that declaration — and only that one — promotes exactly this item to blocking per the declared-style bullet above, while a declared `layered` binds dependency direction instead and leaves this item advisory; an existing convention of concrete injections does not convert this one to `clean`, it is the debt the rule pays down. These land in the verifier result as `should-fix` / `nit` recommendations, not as a `FAIL`.
+- **Advisory findings (recorded as recommendations; verdict MAY still PASS):** each `FILE-SIZE-ADVISORY:` line from the file-size command (a file over the 300-line target but within 400), function >50 effective lines, a single body mixing read+write stages, weak readability, a missing-but-non-critical outcome assertion, weak-but-not-misleading names, priority-between-inputs policy inlined in a service condition instead of a named domain function, an error message asserting a cause the code never observed, a memory / concurrency / batching change with no test pinning the bound it claims, or (hexagonal overlay only) a service dependency this diff adds or modifies that injects a concrete adapter instead of a port — record it with the port sketch; advisory only while the project has not declared `architecture.style = hexagonal`, since that declaration — and only that one — promotes exactly this item to blocking per the declared-style bullet above, while a declared `layered` binds dependency direction instead and leaves this item advisory; an existing convention of concrete injections does not convert this one to `clean`, it is the debt the rule pays down. These land in the verifier result as `should-fix` / `nit` recommendations, not as a `FAIL`.
 - **Output.** Every finding — blocking or advisory — is a structured item in the verifier's worker result (`path:line`, rule, severity, suggested fix) so it carries into Phase 5.5 convergence and the final report. A blocking hit sets the verifier verdict to `FAIL` with the rule cited, using the same verdict machinery as the Discrepancy rule above. The Okstra lead MUST NOT silently downgrade a cited blocking finding to advisory during synthesis; an override requires a concrete cited reason, exactly as for the Discrepancy rule.
 
 ### Fix-run incremental scope (applies when the profile carries a "Fix-Run Carry" block)
 
-A correction-round re-verification (`--dispatch-kind correction-r<N>`, a "Correction Round" block in the task instructions) takes the same scope: the block's findings and the correction diff it names, with every validation command re-run.
+A correction-round re-verification (`--dispatch-kind correction-r<N>`, a "Correction Round" block in the task instructions) takes the same scope: the block's findings and the correction diff it names, with every validation command re-run. The file-size command is the exception: run it against the stage base, never the round's base, because a file the round did not touch keeps the violation the initial diff made.
 
 A fix run re-verifies a stage whose previous run already passed a full static
 sweep and failed only on cited blocking findings. Re-sweeping the whole stage

package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md

@@ -39,4 +39,4 @@
 
 Record candidate validity, unresolved user decisions, and explicitly classified technical facts. The lead chooses the next phase under `## implementation-option-selection` in `prompts/lead/phase-routing.md`.
 
-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.
+When `--clarification-response` carries a technical-verification report, read its source comparison, experiment plans, results and logs. The analysis packet's `## Technical Verification Evidence` section names the result record and the experiment directory (rendered by `okstra_ctl.phases.technical_verification.entry.technical_evidence_packet_block`). 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/python/okstra_ctl/phases/implementation_planning/authoring.py

@@ -733,6 +733,23 @@ _DIR_SNAPSHOT_OWNED_NOTE = (
     "planner-fixable DISAGREE that asks to edit these four fields.\n"
 )
 
+# 구현 executor 는 소스 트리의 실 IO 테스트를 첫 편집 전에 거부한다. 계획이 그런
+# step 을 승인받으면 stage 가 변경 0 으로 멈춘다(2026-10-18 dev-11374 실측).
+_REAL_IO_STEP_NOTE = (
+    "\nReal-IO placement: this step must not create, edit, or run a test that "
+    "opens a real database connection, makes a real network call, or talks to "
+    "a real external service inside the project source test tree (`src/**`, "
+    "`test/**`, `tests/**`, `**/__tests__/**`, `*.spec.*`, `*.test.*`, "
+    "`*.e2e-spec.*`), and its PASS must not depend on a reachable database or "
+    "service. The implementation executor refuses such a step before any edit. "
+    "Real-backend checks belong only in the stage's `Conformance tests:` "
+    "declaration, which the implementation run writes under "
+    "`<task_root>/qa/scripts/`, never commits, and treats as advisory. If this "
+    "step breaks the rule, vote DISAGREE(b) with Fixability planner-fixable and "
+    "name the real-IO test path or command. A test whose collaborator is "
+    "stubbed is not real IO.\n"
+)
+
 
 def _step_coordinate(payload: object, field: str) -> int | None:
     if not isinstance(payload, Mapping):
@@ -1022,6 +1039,8 @@ def _prompt(args: argparse.Namespace) -> str:
         rows.append(_render_prior_steps(item, all_items))
         if item_id.startswith("P-Prep-"):
             rows.append(_PREP_OWNERSHIP_NOTE)
+        if item_id.startswith("P-Step-"):
+            rows.append(_REAL_IO_STEP_NOTE)
         if item_id == "P-Dir-1":
             rows.append(_DIR_SNAPSHOT_OWNED_NOTE)
         split = _render_analyser_split(

package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md

@@ -316,6 +316,20 @@ from both numerator and denominator, and never converted to `DISAGREE`. Voting `
 dependency-missing command instead manufactures a defect the planner cannot fix by editing the plan,
 which is what sends the item into a self-fix round that can only paper over it.
 
+## Real-IO test in a committed step
+
+A `P-Step-*` item that creates, edits, or runs a test opening a real database connection, a real
+network call, or a real external service inside the project source test tree (`src/**`, `test/**`,
+`tests/**`, `**/__tests__/**`, `*.spec.*`, `*.test.*`, `*.e2e-spec.*`), or whose `PASS` depends on a
+reachable database or service, is `DISAGREE(b)` with `planner-fixable`. The implementation executor
+refuses that step before its first edit (`_implementation-executor.md` "Real-IO test isolation"), so
+the stage would end with zero changes. The planner's fix is a stubbed-collaborator unit test in the
+step plus the stage's `Conformance tests:` declaration for the real-backend check. A test whose
+collaborator is stubbed is not real IO. **Enforced:** the rule reaches each verifier on every
+`P-Step-*` item through `okstra plan-items prompt`
+(`okstra_ctl.phases.implementation_planning.authoring._REAL_IO_STEP_NOTE`); the vote itself is
+verifier judgement.
+
 ## Mode constraint
 
 Plan-body verification only supports **lightweight mode** (defined in `prompts/lead/convergence.md` §"Verification Mode"). `full-reanalysis` is not meaningful here because the "original source materials" for a plan item are the worker's own analysis plus the lead-mediated synthesis — there is no independent ground truth to re-read. The manifest's top-level `verificationMode` is ignored for this round; lightweight is always used.

package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md

@@ -147,7 +147,8 @@ Plan for the actual worktree layout before approval. Shared documentation direct
       **Pick the cases by distinct outcome, not by line coverage.** When the stage writes or reconciles state, its meaningfully different outcomes are usually more than three — normal success, target already in the desired state (resume), existing data reused rather than created, a conflicting concurrent state, target absent, and mid-way failure with rollback. Enumerate the ones this stage actually implements and route them across the three lines (the `boundary` line is where resume / already-done / reuse belongs; `failure` carries conflict, absence, and rollback), naming each in the cell rather than collapsing them into "edge input". An implemented outcome with no declared case is a coverage gap the executor will not backfill.
   - **Per-stage subsections** (`## 5.5.<i> Stage <i>: <title>` for each `i`), each containing the four required subsections:
     - `### Carry-In` — for `depends-on (none)`: task-brief only. Otherwise: each depended-on stage's static exit contract + runtime sidecar path `runs/<impl-key>/carry/stage-<i>.json` placeholder.
-    - `### Stepwise Execution Order` — bite-sized table with `step | action | files | command | outcome | expected`. `outcome` is one word — `PASS` or `FAIL` — and `expected` is the sentence saying what that looks like here; a verdict written inside the sentence is not read as one. The `files` cell lists each touched path in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...`), which does not resolve and is rejected by plan-body verification as a kind-b path mismatch. **The narrative row additionally carries `plannedPaths`: the paths this step may write as an array, one repository-relative path per entry, with no globs, exclusions, counts or commentary. Read-only checks use `plannedPaths: []`; their working directory belongs in the command, not the write ledger. Never declare the repository or worktree root. Planning assembly and correction preflight enforce this through `write_policy.planned_path_declaration_errors`.** `files` is the sentence a reader sees; `plannedPaths` is the ledger report assembly preserves and the implementer write policy enforces. When a step legitimately covers a set too large to enumerate, split it or name the directory the set lives under. **Effective row count ≤ 8** (excluding header / divider / blank). Each step is one cohesive, self-contained change. **TDD ordering is MUST, not a preference:** the **first** effective step's `action` cell MUST start with the literal `RED:` and describe the failing test(s) that capture this stage's `Acceptance` **and the three declared `Test case (success|boundary|failure)` lines** (`outcome` = `FAIL`); at least one later `action` cell MUST start with the literal `GREEN:` and describe the minimal implementation that makes it pass (`outcome` = `PASS`); an optional refactor step starts with `REFACTOR:`. **Exemption:** doc-only / config-only / pure-rename stages with no observable runtime behaviour may omit RED/GREEN by declaring one line `TDD exemption: <reason>` in the stage section. A stage that is truthfully none of those three declares `TDD exemption: user-bypass — <the user's words>`, which holds only while the user has granted it for that stage with `okstra prepare --tdd-bypass "<stage>:<reason>"` — never file the nearest of the three instead. Validator S10c enforces RED-first + GREEN; the `outcome` cell agreeing with its prefix is a schema conditional. S10e rejects an unsupported exemption reason and a `user-bypass` with no user grant (`validators/validate-implementation-plan-stages.py`).
+    - `### Stepwise Execution Order` — bite-sized table with `step | action | files | command | outcome | expected`. `outcome` is one word — `PASS` or `FAIL` — and `expected` is the sentence saying what that looks like here; a verdict written inside the sentence is not read as one. The `files` cell lists each touched path in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...`), which does not resolve and is rejected by plan-body verification as a kind-b path mismatch. **The narrative row additionally carries `plannedPaths`: the paths this step may write as an array, one repository-relative path per entry, with no globs, exclusions, counts or commentary. Read-only checks use `plannedPaths: []`; their working directory belongs in the command, not the write ledger. Never declare the repository or worktree root. Planning assembly and correction preflight enforce this through `write_policy.planned_path_declaration_errors`.** **File size:** the implementation run aims for 300 physical lines per source and test file and enforces 400 — a new file over 400, an existing file taken past 400, and a file already over 400 that grows are blocking findings the executor must split in a correction round; the same conditions at 300 are advisory. When a step would add code or tests to a file near or over 300 lines (`wc -l`), plan a new module or test file for that responsibility in `plannedPaths` instead of appending to the existing one. **Enforced at implementation, not here:** `okstra correction file-size` (`scripts/okstra_ctl/file_size_cap.py`), re-run by `okstra stage-done`. `files` is the sentence a reader sees; `plannedPaths` is the ledger report assembly preserves and the implementer write policy enforces. When a step legitimately covers a set too large to enumerate, split it or name the directory the set lives under. **Effective row count ≤ 8** (excluding header / divider / blank). Each step is one cohesive, self-contained change. **TDD ordering is MUST, not a preference:** the **first** effective step's `action` cell MUST start with the literal `RED:` and describe the failing test(s) that capture this stage's `Acceptance` **and the three declared `Test case (success|boundary|failure)` lines** (`outcome` = `FAIL`); at least one later `action` cell MUST start with the literal `GREEN:` and describe the minimal implementation that makes it pass (`outcome` = `PASS`); an optional refactor step starts with `REFACTOR:`. **Exemption:** doc-only / config-only / pure-rename stages with no observable runtime behaviour may omit RED/GREEN by declaring one line `TDD exemption: <reason>` in the stage section. A stage that is truthfully none of those three declares `TDD exemption: user-bypass — <the user's words>`, which holds only while the user has granted it for that stage with `okstra prepare --tdd-bypass "<stage>:<reason>"` — never file the nearest of the three instead. Validator S10c enforces RED-first + GREEN; the `outcome` cell agreeing with its prefix is a schema conditional. S10e rejects an unsupported exemption reason and a `user-bypass` with no user grant (`validators/validate-implementation-plan-stages.py`).
+    - **Real-IO tests stay out of the plan's committed steps (BLOCKING).** A step never creates, edits, or runs a test that opens a real database connection, makes a real network call, or talks to a real external service inside the project source test tree (`src/**`, `test/**`, `tests/**`, `**/__tests__/**`, `*.spec.*`, `*.test.*`, `*.e2e-spec.*`), and no step's `PASS` depends on a reachable database or service. The implementation executor refuses such a step before its first edit (`_implementation-executor.md` "Real-IO test isolation"), so a plan that contains one stops the stage with zero changes (observed 2026-10-18, dev-11374: a live-MySQL `test/font-pairing.e2e-spec.ts` planned in steps 1, 4 and 5). The committed RED/GREEN steps test the adapter with its injected collaborator stubbed — the exact query text, its replacements, and the returned rows — and run without any backend. Real-backend verification is declared only as this stage's `Conformance tests:` line below (`requires=[db|http|external]`): the implementation run writes that script under `<task_root>/qa/scripts/`, runs it against a local or replica backend when one is reachable, never commits it, and records a non-PASS or unreachable backend as advisory. Read a brief line such as `verify: integration test against a test database` as that conformance declaration, not as a committed test. Do not plan a shared real-DB guard, a test DDL fixture, or an edit to an existing real-IO suite in source to support it. **Enforced:** every `P-Step-*` item of the §5.5.9 plan-body round carries this rule to its verifiers (`okstra_ctl.phases.implementation_planning.authoring._REAL_IO_STEP_NOTE`), which vote `DISAGREE(b)` on a step that breaks it; no path pattern tells a mocked test from a live one, so no validator checks it.
     - **The `command` cell runs inside an okstra task worktree, not a bare checkout (BLOCKING).** okstra provisions `.okstra`, the configured sync entries (`.project-docs`, `.claude`, …), and — for `implementation` — a nested `stage-<N>/` worktree into the tree the step executes in. Two consequences bind every command you write:
       - **Clean-tree assertions use `okstra worktree-status --check-clean`.** A bare `git status --porcelain` is never empty there, so an assertion built on one fails on okstra's scaffolding rather than on the stage's work. The okstra command asks the same question over source paths only and exits 1 when dirty, so it stands alone as a step's assertion: `okstra worktree-status --check-clean`. Validator S13 rejects the bare form. Do not add a `git tag stage-<N>-exit` to the step. Stage completion records the commit in the consumer ledger without creating or moving git tags.
       - **Never read an `.okstra/` artifact back out of a git object.** `.okstra/**` is gitignored and never committed — the executor aborts a commit that stages an ignored path and the verifier reports a committed `.okstra` path as a branch defect — so `git cat-file -e <tag>:.okstra/…`, `git show <tag>:.okstra/…`, and every variant of that read can never resolve, at any tag, in any stage. A later stage that needs a QA artifact reads it from the working tree or receives it through the carry sidecar / verifier result; do not design a stage contract around one being reachable from a tag. Validator S12 rejects the read.

package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json

@@ -1,7 +1,7 @@
 {
-  "allowed": "  - entering this phase only when the cited final-verification report's verdict is release-ready — `Verdict Token` exactly `accepted`, or exactly `conditional-accept` with every Conditional Acceptance Condition row declaring `blocksReleaseHandoff: false` (`okstra_ctl.release_gate.release_handoff_allowed`)\n  - asking the user (via `AskUserQuestion` / interactive prompt) which delivery action to take: `local checkout`, `push + PR`, or `skip` (end the run)\n  - asking the user to pick a PR base branch from `staging` | `preprod` | `prod` | `main` | `dev` | a user-supplied branch name\n  - drafting PR title and PR body **inline as the Okstra lead** (no drafter worker and no delegated dispatch); the lead reviews its own draft with the user before any mutating git / gh command runs\n  - read-only git inspection: `git status`, `git diff`, `git log`, `git rev-parse`\n  - pushing the current feature branch to its origin remote via `git push -u origin <current-branch>` (the feature branch only — NEVER the base branch)\n  - creating a pull request via `gh pr create --base <chosen-base> --head <current-branch>`; if a PR with the same head already exists, surface its URL and skip creation\n  - the lead writes the final report directly (no `Report writer worker` dispatch); the report still conforms to the standard final-report template",
+  "allowed": "  - entering this phase only when the cited final-verification report's verdict is release-ready — `Verdict Token` exactly `accepted`, or exactly `conditional-accept` with every Conditional Acceptance Condition row declaring `blocksReleaseHandoff: false` (`okstra_ctl.release_gate.release_handoff_allowed`)\n  - asking the user (via `AskUserQuestion` / interactive prompt) which delivery action to take: `local checkout`, `push + PR`, or `skip` (end the run)\n  - asking the user to pick a PR base branch from `staging` | `preprod` | `prod` | `main` | `dev` | a user-supplied branch name\n  - drafting PR title and PR body **inline as the Okstra lead** (no drafter worker and no delegated dispatch); the lead reviews its own draft with the user before any mutating git / gh command runs\n  - read-only git inspection: `git status`, `git diff`, `git log`, `git rev-parse`\n  - pushing the current feature branch to its origin remote via `git push -u origin <current-branch>` (the feature branch only — NEVER the base branch)\n  - creating a pull request via `gh pr create --base <chosen-base> --head <current-branch>`; if a PR with the same head already exists, surface its URL and skip creation\n  - the lead writes the report narrative at the run manifest's `reportNarrativePath` directly (no `Report writer worker` dispatch); `okstra report-finalize` assembles the final report from it",
   "forbidden": [
-    "entering this phase when the cited final-verification `Verdict Token` is `conditional-accept` or `blocked`, or when no final-verification report is cited",
+    "entering this phase when a cited final-verification verdict is not release-ready — `Verdict Token` `blocked` or any token other than `accepted` / `conditional-accept`, a `conditional-accept` with no Conditional Acceptance Condition row or with any row whose `blocksReleaseHandoff` is not `false` (`okstra_ctl.release_gate.release_handoff_allowed`) — or when no final-verification report is cited",
     "local commit commands of any kind (`git add`, `git commit`, `git restore --staged`, `git stash`), and any direct `git merge` / `git rebase` / `git rebase --onto` / `git cherry-pick` / `git commit --amend` run by the lead. Runtime exceptions are dependency-ordered rebases by `okstra_ctl.stage_rebase` (which invalidate verification and stop PR delivery), and merge commits on a dedicated multi-predecessor `merge-base` branch. Never merge a moving predecessor or origin branch into a downstream stage to update its base.",
     "any git push variant that rewrites remote history, regardless of intent or whether the user said \"force it\": `git push --force`, `git push --force-with-lease`, `git push -f`, `git push +<refspec>`, or any other history-rewriting invocation",
     "pushing directly to a release base branch — i.e. `git push origin <branch>` where `<branch>` is `main`, `master`, `prod`, `preprod`, `staging`, `dev`, or the branch the user chose as the release base in this run. The only permitted push targets are the branches `okstra handoff pr-plan` listed for this run (each stage `head_branch`, and any `merge-base` branch).",

package/runtime/python/okstra_ctl/phases/release_handoff/profile.md

@@ -4,12 +4,12 @@
   the `releaseBase` the user picked. The report is the only place a reader learns which stages
   shipped and in what order their PRs must be merged — the branch names do not say.
 - Purpose: take a release-ready single-stage final-verification verdict for each already-committed implementation stage and turn it into a delivered push and/or pull request, with explicit user selection at every delivery step. **One stage is one PR.** The PR head is that stage's stack branch (`<prefix>-<task-id>-s<N>`); nothing is squashed or collected into a bundle branch. Runtime dependency rebases happen before delivery and invalidate the prior verification.
-- **Execution model: single-lead, no worker dispatch.** This phase is a thin orchestrator over `git` / `gh`; it does NOT dispatch teammates, does NOT dispatch analysis or drafter sub-agents, and does NOT run convergence. The host-native Okstra lead performs every step inline (drafting PR text, asking the user, running git / gh, writing the final report) — see "Lead-only contract" below.
+- **Execution model: single-lead, no worker dispatch.** This phase is a thin orchestrator over `git` / `gh`; it does NOT dispatch teammates, does NOT dispatch analysis or drafter sub-agents, and does NOT run convergence. The host-native Okstra lead performs every step inline (drafting PR text, asking the user, running git / gh, writing the report narrative) — see "Lead-only contract" below.
 - Worker roster: none — `profile.json` declares no roles; the run is executed entirely by the Okstra lead.
 - Lead-only contract (replaces the shared team contract for this phase):
   - The host-native Okstra lead is the sole agent for this run. No worker dispatch, no teammates, no parallel sub-agents, no convergence loop. Do NOT run `okstra convergence` in any form: prepare already wrote this run's convergence state as "not run — fewer than two analysers", which is the record report assembly reads. **Enforced:** `okstra_ctl.render._initialize_lead_only_convergence` writes it when the run has no analysers, and leaves an existing state alone.
   - The lead drafts each stage's PR title and PR body **inline** by reading the run brief, that stage's cited final-verification report, `git log --oneline <stage base>..<stage head>`, and `git diff <stage base>..<stage head> --stat`. No drafter worker is dispatched.
-  - The lead authors the final-report file directly (no `Report writer worker` dispatch). The report still conforms to the standard `templates/reports/final-report-v2.template.md` structure, including the `## 5.6 Release Handoff Deliverables` section.
+  - The lead authors the report narrative directly (no `Report writer worker` dispatch) and never writes `final-report-*.data.json`. Write the narrative to the path the run manifest names in `reportNarrativePath`. It carries only the writer-owned fields (`humanSummary`, `summary`, `verdictCard`, `finalVerdict`, `rationale`, `recommendedNextSteps`, `followUpTasks`, and `releaseHandoff` with its `userNarrative`) in the narrative line grammar of `report_narrative.NARRATIVE_GRAMMAR_INSTRUCTIONS`: the first line is `# OKSTRA Report Narrative`, followed only by `- **Field Name**`, `- Item <N>` and `> value` lines, each value indented two spaces deeper than its label. `okstra report-finalize` assembles `data.json` from this narrative plus the approval, activity, team-state and convergence ledgers prepare already created. A missing or unparseable narrative fails the `project-activity` step with `owner=lead`. **Enforced:** `report_inputs._LEAD_AUTHORED_NARRATIVE_TASK_TYPES`, read by `report_assembly.assemble_report`.
   - The shared anti-escalation rule from the common contract still applies: do not start any other lifecycle phase from inside this run.
   - The shared "authority & permissions assumption" rule from the common contract still applies: assume the user holds every permission needed; do not block on hypothetical approvals.
 - Pre-handoff entry gate (mandatory — refuse to start if any item fails):