okstra 0.220.0 → 0.220.1

package/dist/lib/paths.mjs

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { existsSync } from "node:fs";
 import { getPackageRoot, getPackageVersion } from "./version.mjs";
 function isStaleTmpHome(p) {
-    // tests/conftest.py creates the isolated home as `<tmp_path>/.okstra-isolated`
+    // tests/_okstra_isolation.py creates the isolated home as `<tmp_path>/.okstra-isolated`
     // under the system temp dir. Only a deleted one (env leaked, dir gone) heals;
     // a soon-to-be-created `.okstra` temp home or a custom home is left untouched.
     if (!p.endsWith("/.okstra-isolated"))

package/dist/lib/paths.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"paths.mjs","sourceRoot":"","sources":["../../src/lib/paths.mts"],"names":[],"mappings":"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"}
+{"version":3,"file":"paths.mjs","sourceRoot":"","sources":["../../src/lib/paths.mts"],"names":[],"mappings":"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"}

package/docs/cli.md

@@ -869,7 +869,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra chat <rooms\|create\|join\|members\|send\|unread\|inbox\|log\|ack>` | Global rooms under `~/.okstra/chat`. Join takes an explicit `--name`. Send takes exactly one of `--to` (`all` or a member; may equal `--as`) or `--reply-to` (an id in that room), and exactly one of `--body` or `--body-file`; a body may span several lines. A reply inherits `to` from the parent (`all` stays `all`, otherwise the parent's `from`). Unread is the inbox after the read cursor minus messages the participant sent; it does not move the cursor. `inbox` and `log` keep those arrivals, including after ack. Rows are `id @from YYYY-MM-DD HH:MM body`; a reply inserts `↑parentId` after the time; the second and later lines of a body follow on rows indented by two spaces. `ack --through` rejects an id behind the current cursor. Room and display names `.` and `..` are reserved. A `.lock` left by a dead process (pid recorded in the file) or older than 5 s is reclaimed. CLI basis of the `okstra-chat` skill. |
 | `okstra model-io active-context-input --project-root <dir> --run-manifest <path>` | Resolve the prior implementation-planning active context only through the current project and run authority, then emit fixed fields such as the executor base ref. Caller-supplied active-context paths are not accepted. |
 | `okstra convergence prepare-groups --run-manifest <path> --input <grouping.md>` | Parse fixed grouping Markdown, validate distinct per-worker evidence and group semantics against the run authority, then publish the schema-valid groups artifact at the run-owned path. |
-| `okstra manager <init\|discover-projects\|new\|task\|list\|remove\|view> [--json]` | Public CLI for grouping cross-project okstra tasks into manager-owned context. The default is purpose-specific fixed text for model use; `--json` preserves the machine contract and exit codes. `new project --project-root` accepts only existing directories and performs setup-equivalent registration only if `.okstra/project.json` is absent. `list managers`, `list projects --manager-id <id>` and `list tasks --manager-id <id>` enumerate manager state; `view --manager-id <id>` writes `~/.okstra/managers/<id>/view/index.html` and prints its path and `file://` URL. `task split --plan <json>` writes one validated brief with a `## Project Scope` section into each project an issue is assigned to and registers those children; `task run` then passes `--task-brief`. For a child whose task type is `discussion`, `task sync` records a `discussion` block read from the discussion record without writing to it — state (`draft`, `completed`, or `unknown` when the record cannot be read), phase, pending questions, revisions with their change reasons, and each follow-up's pinned revision and impact-review state, re-read from the follow-up's brief — and `task status` counts the child under `discussion`, never under `done`. `task run` for a child without a registered brief takes the brief that `okstra discussion follow-up-brief` wrote for it, found in the last-synced links of a discussion child of the same manager task. `list task-groups` lists groups including empty ones; `task update` edits a task's objective, common brief or progress mode; `remove project`, `remove task`, `remove task-group` and `task remove-child` print their targets and delete manager files only with `--confirm`, and `remove project` keeps the project's children marked unlinked. |
+| `okstra manager <init\|discover-projects\|new\|task\|list\|remove\|view> [--json]` | Public CLI for grouping cross-project okstra tasks into manager-owned context. The default is purpose-specific fixed text for model use; `--json` preserves the machine contract and exit codes. `new project --project-root` accepts only existing directories and performs setup-equivalent registration only if `.okstra/project.json` is absent. `list managers`, `list projects --manager-id <id>` and `list tasks --manager-id <id>` enumerate manager state; `view --manager-id <id>` writes `~/.okstra/managers/<id>/view/index.html` and prints its path and `file://` URL. `task split --plan <json>` writes one validated brief with a `## Project Scope` section into each project an issue is assigned to and registers those children; `task run` then passes `--task-brief`. `task run` re-reads the target child's state from its project and refuses a child that is already done there, naming its last phase and report, unless `--allow-completed` is given. For a child whose task type is `discussion`, `task sync` records a `discussion` block read from the discussion record without writing to it — state (`draft`, `completed`, or `unknown` when the record cannot be read), phase, pending questions, revisions with their change reasons, and each follow-up's pinned revision and impact-review state, re-read from the follow-up's brief — and `task status` counts the child under `discussion`, never under `done`. `task run` for a child without a registered brief takes the brief that `okstra discussion follow-up-brief` wrote for it, found in the last-synced links of a discussion child of the same manager task. `list task-groups` lists groups including empty ones; `task update` edits a task's objective, common brief or progress mode; `remove project`, `remove task`, `remove task-group` and `task remove-child` print their targets and delete manager files only with `--confirm`, and `remove project` keeps the project's children marked unlinked. |
 | `okstra rollup [--task-group <group>] [--project-root <dir>] [--cwd <dir>] [--text\|--json]` | Read-only backend for the okstra-rollup skill. `--text` emits ordered fixed labels for model use. The default and `--json` preserve the full machine JSON contract and exit codes. Omitting `--task-group` targets the whole project catalog. |
 | `okstra usage-report [--days <positive-int>] [--project-root <dir>] [--cwd <dir>] [--text\|--json]` | Read-only backend for the okstra-usage skill. `--text` emits ordered fixed labels for model use. The default and `--json` preserve the full machine JSON contract and exit codes. Defaults to the current project's last 30 days. |
 | `okstra worker-state transition --team-state <path> --worker <id> --status <in-progress\|completed\|timeout\|error\|not-run> [--reason <text>] [--model <execution-value>]` | Atomically update one persisted worker row. `in-progress` records the authoritative `startedAt` and clears `endedAt`; terminal states record `endedAt`; `timeout`, `error`, and `not-run` require a reason. Dispatch adapters use this same transition path, so CLI-backed and in-process orchestration share the status timestamp contract |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.220.0",
+  "version": "0.220.1",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.220.0",
-  "builtAt": "2026-10-17T11:04:20.410Z",
+  "package": "0.220.1",
+  "builtAt": "2026-10-18T05:15:37.569Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -260,7 +260,7 @@ Follow the launch prompt's operation-level progress guidance: name the actual pr
 
 A single okstra run frequently spans 30–120 minutes with multi-minute silent windows while workers run; without progress signals the user cannot distinguish "still working" from "hung". Lead MUST emit a single short progress line at each checkpoint below — plain user-facing text in a separate brief message (not buried inside a tool call), one line per checkpoint, format: `PROGRESS: <phase-id> <verb-phrase>`. Emit the line raw — the literal `PROGRESS:` token must begin the line. Do NOT wrap it in inline-code backticks (`` `PROGRESS: ...` ``) or a ```` ``` ```` code fence; markdown wrapping is what the post-hoc conformance validator scrapes around, and raw emit keeps the signal unambiguous.
 
-Record each checkpoint with `okstra lead-progress append --project-root <dir> --run-manifest <path> --phase <phase-id>`, then emit the `progressLine` it prints as the user-facing line. The command resolves `leadEventsPath` from the run manifest and writes the checkpoint there — on a host whose adapter declares `sessionAccounting: artifact-only` that ledger is the only place the post-hoc validator can read it, so a conversation line alone leaves no trace and the run is reported as missing the checkpoint. Pass `--worker <role>` on the per-worker checkpoints (it rewrites a phase-specific functional label into the roster role team-state records), `--field NAME=VALUE` for the remaining `key=value` tokens in the order the line carries them, and `--detail <text>` where the line ends in a verb phrase; the wording listed below is the default for the fixed-prose checkpoints.
+Record each checkpoint with `okstra lead-progress append --project-root <dir> --run-manifest <path> --phase <phase-id>`, then emit the `progressLine` it prints as the user-facing line. The command resolves `leadEventsPath` from the run manifest and writes the checkpoint there — on a host whose adapter declares `sessionAccounting: artifact-only` that ledger is the only place the post-hoc validator can read it, so a conversation line alone leaves no trace and the run is reported as missing the checkpoint. Pass `--worker <role>` on the per-worker checkpoints (it rewrites a phase-specific functional label into the roster role team-state records), `--field NAME=VALUE` for the remaining `key=value` tokens in the order the line carries them, and `--detail <text>` where the line ends in a verb phrase; the wording listed below is the default for the fixed-prose checkpoints. The default follows what happened: a second `phase-1-intake` call in the same run renders `complete`, and `phase-6-synthesis` in a task type whose profile has no report-writer role renders `authoring final report`. **Enforced:** `_default_detail` in `scripts/okstra_ctl/lead_progress.py`, `tests/contract/test_lead_progress_cli.py`.
 
 Some checkpoints are recorded by the command that performs the step, because that command holds the fact the line states:
 
@@ -288,7 +288,7 @@ Use the exact CLI projection: `id`, `agent`, quoted `summary`, comma-joined `ite
 Required checkpoints:
 
 - `PROGRESS: phase-1-intake reading task bundle` — at the start of Phase 1, before issuing parallel Read calls.
-- `PROGRESS: phase-1-intake complete` — after all intake reads return.
+- `PROGRESS: phase-1-intake complete` — after all intake reads return. Call `lead-progress append --phase phase-1-intake` again; the second call in a run renders this line.
 - `PROGRESS: phase-2-prompts preparing <N> worker prompts` — at the start of Phase 2, before any `Write` to the assigned prompt paths.
 - `PROGRESS: phase-3-team-create <adapter-specific-status>` — after selected-adapter setup is recorded in team-state. The stable phase id is retained for artifact compatibility. When the first dispatch writes the implicit-team marker, that dispatch command records the line.
 - `PROGRESS: phase-4-dispatch worker=<role> model=<model>` — once per worker, immediately before `dispatch_worker`. `<role>` is the **roster** role, exactly as team-state's `workers[].role` records it (`Claude worker`, `Codex worker`) — the checkpoint is matched against that entry, so a phase-specific functional label (`Claude verifier`, `Codex executor`) names no roster worker and fails the check. Only `claude-worker`-style hyphenation of the same roster role is also accepted.
@@ -299,7 +299,7 @@ Required checkpoints:
 - `PROGRESS: phase-5.5-convergence round=<N> queue=<count>` — at the start of each convergence round (Phase 5.5). `<N>` and `<count>` are the `round` and `inputQueueSize` that `okstra convergence plan-round` prints for that round, copied verbatim.
 - `PROGRESS: phase-5.6-critic provider=<provider> gaps=<n>` — after the critic result is collected (Phase 5.6, opt-in; the critic dispatch itself fires concurrently with the first 5.5 reverify round). Omitted when `convergence.critic.enabled == false`.
 - `PROGRESS: phase-batch-cleanup panes=<n>` — immediately after cleaning up the previous batch's panes, at each batch boundary (① just before the first `phase-5.5-convergence` round ② just before the `phase-6-synthesis` report-writer dispatch). `<n>` is the number of panes closed at that boundary — the panes of dispatches this run recorded and that have since finished — counted by `okstra team reclaim --project-root <dir> --run-manifest <path>` as the panes that pass closed, never estimated; no `--dry-run` pass is needed to learn it. A pane the harness opened for its own teammate carries no recorded id, so it is not counted and not closed. Expose only the counts and NEVER expose a raw `paneId` or worker handle. Just before the first batch (analysis-worker dispatch) there is nothing to clean up, so it is a no-op and the marker is omitted.
-- `PROGRESS: phase-6-synthesis dispatching report-writer-worker` — at the start of Phase 6. `team dispatch` (cmux-pane run only) and `worker-dispatch` record it on the first report-writer dispatch; on any other backend a `team dispatch` run appends it with `lead-progress append`.
+- `PROGRESS: phase-6-synthesis dispatching report-writer-worker` — at the start of Phase 6. `team dispatch` (cmux-pane run only) and `worker-dispatch` record it on the first report-writer dispatch; on any other backend a `team dispatch` run appends it with `lead-progress append`. A lead-only task type (no report-writer role in its profile, e.g. `release-handoff`) dispatches no report writer; its line reads `phase-6-synthesis authoring final report`.
 - `PROGRESS: phase-5.5.9-plan-verify round=<N> items=<count>` — immediately before dispatching each plan-body verification round (`implementation-planning` only; see `plan-body-verification` (the absolute path in **Okstra Runtime Resources**) §"Round protocol"). Each round is a worker batch like any other, so round 2 and later MUST be preceded by a `phase-batch-cleanup` line reclaiming the previous round's verifiers. The numbering keeps this line sorted where the work happens — after Phase 6, because the round verifies the drafted plan body.
 - `PROGRESS: user-confirm <C-NNN> <the question, one line>` — immediately before asking the user about anything that would otherwise become an open `Blocks=approval` row (see "User confirmation before an approval blocker" below). Not tied to a phase: it fires wherever the blocker surfaces. `<C-NNN>` is the id the row will carry, so the answer and the row can be matched afterwards.
 - `PROGRESS: phase-7-persist updating manifests` — at the start of Phase 7. `okstra report-finalize` records it.

package/runtime/python/okstra_ctl/business_flow/engine.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import hashlib
 import json
+import re
 from dataclasses import asdict, replace
 from datetime import datetime, timezone
 from pathlib import Path
@@ -197,10 +198,15 @@ def _accept_return(call: PreparedCall, returned: bytes) -> str:
     ).returned_body
 
 
+_FENCED_JSON = re.compile(r"^```json\n(.*?)\n```$", re.MULTILINE | re.DOTALL)
+
+
 def _parse_result(body: str, path: Path) -> BusinessResult:
     text = body.strip()
-    if text.startswith("```json\n") and text.endswith("\n```"):
-        text = text[8:-4]
+    # 조사자는 "JSON만 반환" 지시에도 객체를 짧은 서문·맺음말과 함께 펜스로 감싸 돌려준다.
+    fenced = _FENCED_JSON.findall(text)
+    if len(fenced) == 1:
+        text = fenced[0]
     try:
         result = json.loads(text)
     except json.JSONDecodeError as exc:
@@ -379,6 +385,8 @@ def _instructions(
             "Return only one JSON object matching the schema below.",
             "Read the listed source roots and source artifacts only. Do not edit files, execute tests, start services, deploy or migrate.",
             "Inspect inbound AND outbound dependencies across all candidates, including indirect call/event/queue/shared-data/file/batch relationships. Name every uninspected candidate or missing branch in gaps.",
+            "In relationships, from and to must each be a projectId listed under projects in the Source Material; put modules, files and planned work in data, not in from/to.",
+            "Cite evidence only from files Git tracks or would add in a candidate root. Git-ignored files (for example .project-docs/) are outside the captured source inventory and are rejected; name what you learned from them in gaps instead.",
             "Explain the product business from start to finish for a new developer: purpose, rules, input/output, states, failure, retry and recovery. Link each step and relationship to factKeys.",
             "Use stable keys in business/subject/attribute form. Facts are source-backed assertions; expected changes remain expected. Cite inspected evidence with one-based line/endLine; each excerpt must copy the whole line..endLine range verbatim, including indentation, with no elision or omitted lines. Tests are static evidence unless a supplied existing verification record supports the execution claim.",
             "For post mode, use the supplied project-specific baseline. Never invent missing before-state. Describe the actual delta and distinguish confirmed side effects from risks.",

package/runtime/python/okstra_ctl/lead_progress.py

@@ -18,12 +18,14 @@ import argparse
 import json
 import sys
 from collections.abc import Mapping, Sequence
+from dataclasses import replace
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
 from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
-from okstra_ctl.lead_events import LeadEvent, append_lead_event
+from okstra_ctl.lead_events import LeadEvent, append_lead_event, read_lead_events
+from okstra_ctl.phases import catalog
 
 
 class ProgressRecordError(ValueError):
@@ -64,6 +66,11 @@ _DEFAULT_DETAIL: Mapping[str, str] = {
     "phase-7-teardown": "shutting-down-workers",
 }
 
+# phase 하나에 문구가 둘인 체크포인트. 고정 표만으로는 두 번째 호출이 첫 문구를
+# 다시 내므로, 원장과 task type 을 보고 고른다.
+_INTAKE_COMPLETE_DETAIL = "complete"
+_LEAD_ONLY_SYNTHESIS_DETAIL = "authoring final report"
+
 
 def _utc_now() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -165,6 +172,39 @@ def _parse_field(raw: str) -> tuple[str, str]:
     return name.strip(), field_value.strip()
 
 
+def _intake_already_started(events_path: Path, event: LeadEvent) -> bool:
+    return any(
+        prior.event_type == "progress"
+        and prior.details.get("phase") == "phase-1-intake"
+        and (prior.task_key, prior.task_type, prior.run_seq)
+        == (event.task_key, event.task_type, event.run_seq)
+        for prior in read_lead_events(events_path)
+    )
+
+
+def _task_type_dispatches_report_writer(task_type: str) -> bool:
+    if task_type not in catalog.task_types():
+        return True
+    package = catalog.phase_record(task_type).package_name
+    profile = _read_json_object(
+        Path(catalog.__file__).parent / package / "profile.json", "phase profile"
+    )
+    return any(
+        isinstance(row, Mapping) and row.get("roleId") == "report-writer"
+        for row in profile.get("roles") or []
+    )
+
+
+def _default_detail(phase: str, events_path: Path, event: LeadEvent) -> str | None:
+    if phase == "phase-1-intake" and _intake_already_started(events_path, event):
+        return _INTAKE_COMPLETE_DETAIL
+    if phase == "phase-6-synthesis" and not _task_type_dispatches_report_writer(
+        event.task_type
+    ):
+        return _LEAD_ONLY_SYNTHESIS_DETAIL
+    return _DEFAULT_DETAIL.get(phase)
+
+
 def render_progress_line(
     phase: str,
     fields: Sequence[tuple[str, str]] = (),
@@ -199,7 +239,9 @@ def record_progress(
         )
         ordered.append(("worker", role))
     ordered.extend(fields)
-    line = render_progress_line(phase, ordered, detail)
+    events_path = _resolve_project_path(
+        project_root, _require_string(manifest, "leadEventsPath")
+    )
     event = LeadEvent(
         event_type="progress",
         lead_runtime=_require_string(manifest, "leadRuntime"),
@@ -207,15 +249,15 @@ def record_progress(
         task_type=_require_string(manifest, "taskType"),
         run_seq=_manifest_run_seq(manifest),
         timestamp=timestamp or _utc_now(),
-        details={
-            "phase": phase,
-            "line": line,
-            **({name: field_value for name, field_value in ordered}),
-        },
-    )
-    events_path = _resolve_project_path(
-        project_root, _require_string(manifest, "leadEventsPath")
     )
+    if detail is None:
+        detail = _default_detail(phase, events_path, event)
+    line = render_progress_line(phase, ordered, detail)
+    event = replace(event, details={
+        "phase": phase,
+        "line": line,
+        **({name: field_value for name, field_value in ordered}),
+    })
     append_lead_event(events_path, event)
     return event, warning
 
@@ -306,7 +348,10 @@ def _parser() -> argparse.ArgumentParser:
         help="extra `NAME=VALUE` token, in the order given")
     append_parser.add_argument(
         "--detail",
-        help="verb phrase after the fields; contract wording is the default")
+        help="verb phrase after the fields; contract wording is the default "
+             "(a second phase-1-intake renders `complete`, and phase-6-synthesis "
+             "in a task type without a report writer renders "
+             "`authoring final report`)")
     return parser
 
 

package/runtime/python/okstra_ctl/manager_cli.py

@@ -332,6 +332,7 @@ def _parser() -> argparse.ArgumentParser:
     run.add_argument("--task-group", required=True)
     run.add_argument("--task-id", required=True)
     run.add_argument("--child-task-id", default=None)
+    run.add_argument("--allow-completed", action="store_true")
 
     split = task_sub.add_parser("split")
     split.add_argument("--manager-id", required=True)
@@ -466,6 +467,7 @@ def main(argv: list[str] | None = None) -> int:
                     args.task_id,
                     args.project_id,
                     child_task_id=args.child_task_id,
+                    allow_completed=args.allow_completed,
                 ),
                 args.json,
             )

package/runtime/python/okstra_ctl/manager_launch.py

@@ -20,7 +20,7 @@ from .manager_paths import (
     task_manifest_path,
 )
 from .manager_store import ManagerError, _now_iso, _read_json, _read_json_default, _write_json
-from .manager_sync import _resolve_task_root_read_only
+from .manager_sync import _snapshot_child, summary_bucket
 
 
 WORKER_DISPATCH_BACKEND = "subagent"
@@ -222,6 +222,25 @@ def _record_launch_prepared(
     )
 
 
+def _current_child_state(project_root: str, child: dict, target_task_key: str, *, allow_completed: bool) -> dict:
+    """대상 하위 task 를 마지막 sync 가 아니라 지금 프로젝트에서 다시 읽는다.
+
+    스냅샷은 sync 시점 값이라, 그 뒤 프로젝트에서 끝난 task 에 런치 패킷을 만들면 같은 일을 두 번 시킨다.
+    """
+    current = _snapshot_child(Path(project_root), {**child, "taskKey": target_task_key})
+    if current.get("error"):
+        raise ManagerError(f"{target_task_key}: cannot read child task state: {current['error']}")
+    if summary_bucket(current) == "done" and not allow_completed:
+        report = current.get("latestReportRecordPath") or ""
+        raise ManagerError(
+            f"{target_task_key}: already done in its project "
+            f"(last phase {current.get('lastCompletedPhase') or current.get('currentPhase') or 'unknown'}, "
+            f"report {Path(project_root) / report if report else 'none'}); nothing to launch. "
+            "Run `okstra manager task sync` to refresh the manager, or pass --allow-completed to prepare a launch anyway"
+        )
+    return current
+
+
 def build_launch_packet(
     home: Path,
     manager_id: str,
@@ -230,6 +249,7 @@ def build_launch_packet(
     project_id: str,
     *,
     child_task_id: str | None = None,
+    allow_completed: bool = False,
     now: str | None = None,
 ) -> dict:
     manifest = _read_json(task_manifest_path(home, manager_id, task_group, task_id))
@@ -244,6 +264,7 @@ def build_launch_packet(
     target_task_key = _target_task_key(project_id, task_group, child_task_id_value)
     _validate_child_task_key(child, target_task_key)
     project_root = _validated_project_root(project)
+    current = _current_child_state(project_root, child, target_task_key, allow_completed=allow_completed)
     created_at = now or _now_iso()
     brief_path = (Path(str(child["briefPath"])) if child.get("briefPath")
                   else _discussion_follow_up_brief(snapshot, target_task_key))
@@ -277,7 +298,7 @@ def build_launch_packet(
     # phase 를 채워야 하는데, 두 값이 다 주어지면 그 채우기를 건너뛴다(autofill_from_manifest).
     # 토론 후속 브리프는 권장 phase 를 따로 적지 않아도 requirements-discovery 에서 시작한다.
     recommended = child.get("recommendedPhase") or (DISCUSSION_FOLLOW_UP_PHASE if discussion_ref else "")
-    if recommended and _resolve_task_root_read_only(Path(project_root), target_task_key) is None:
+    if recommended and not current["exists"]:
         run_args.extend(["--task-type", str(recommended)])
     if brief_path is not None:
         run_args.extend(["--task-brief", str(brief_path)])

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):

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

@@ -33,7 +33,7 @@ When a predecessor advances, `okstra_ctl.stage_rebase.synchronize_stage_stack` r
 
 Because the PRs are a stack, they must be merged in dependency order with a merge commit or a rebase-merge. A squash replaces the commits the next PR's base points at, so the stack breaks — every PR body states this, and the lead never merges.
 
-This phase has no worker dispatch. It does not use a provider or report-writer roster; the host-native Okstra lead performs git/gh inspection, user questions, the PR draft, and the final report inline.
+This phase has no worker dispatch. It does not use a provider or report-writer roster; the host-native Okstra lead performs git/gh inspection, user questions, the PR draft, and the report narrative inline; `okstra report-finalize` assembles the final report from that narrative.
 
 ## 2. okstra-run wizard flow
 

package/runtime/python/okstra_ctl/report_assembly.py

@@ -762,7 +762,7 @@ def _attach_machine_planning(
     _sync_human_summary_with_plan_body_gate(data, projection)
 
 
-def _schema_owner(error: str) -> str:
+def _schema_owner(error: str, narrative_owner: str) -> str:
     field = error.split(" ", 1)[0]
     owners = {
         "executionStatus": "team-state",
@@ -781,8 +781,8 @@ def _schema_owner(error: str) -> str:
     if "planBodyVerification" in error:
         return "convergence"
     if "selectedDirectionRef" in error:
-        return "report-writer"
-    return owners.get(field.split(".", 1)[0], "report-writer")
+        return narrative_owner
+    return owners.get(field.split(".", 1)[0], narrative_owner)
 
 
 def _publish(
@@ -864,7 +864,7 @@ def assemble_report(
     path_errors = planned_path_declaration_errors(data)
     if path_errors:
         raise ReportAssemblyError(tuple(
-            AssemblyIssue("report-writer", str(inputs["narrative"].path), error.split(":", 1)[0], error)
+            AssemblyIssue(inputs["narrative"].owner, str(inputs["narrative"].path), error.split(":", 1)[0], error)
             for error in path_errors
         ))
     direction_errors = selected_direction_plan_errors(
@@ -888,7 +888,7 @@ def assemble_report(
         raise ReportAssemblyError(
             tuple(
                 AssemblyIssue(
-                    _schema_owner(error),
+                    _schema_owner(error, inputs["narrative"].owner),
                     str(target),
                     error.split(" ", 1)[0],
                     error,

package/runtime/python/okstra_ctl/report_inputs.py

@@ -28,6 +28,10 @@ _INPUT_FIELDS = (
     ("convergence", "convergence", "convergenceStatePath"),
 )
 
+# 워커 없이 리드가 리포트까지 쓰는 phase. 서사의 저자가 리드이므로, 서사가
+# 없을 때 조립이 report-writer 를 지목하면 띄울 수 없는 워커를 찾게 된다.
+_LEAD_AUTHORED_NARRATIVE_TASK_TYPES = frozenset({"release-handoff"})
+
 _PLANNING_INPUT_FIELDS = (
     ("design-preparation", "design-surface-detector", "designPreparationPath"),
     ("plan-body-verification", "convergence", "planBodyVerificationPath"),
@@ -63,8 +67,13 @@ def report_input_paths(
         if manifest.get("taskType") == "implementation-planning"
         else ()
     )
+    lead_authored = manifest.get("taskType") in _LEAD_AUTHORED_NARRATIVE_TASK_TYPES
     rows = tuple(
-        ReportInputPath(key, owner, _project_path(project_root, manifest.get(field), field))
+        ReportInputPath(
+            key,
+            "lead" if lead_authored and key == "narrative" else owner,
+            _project_path(project_root, manifest.get(field), field),
+        )
         for key, owner, field in fields
     )
     if len({row.key for row in rows}) != len(rows):

package/runtime/python/okstra_ctl/wizard/engine.py

@@ -96,7 +96,7 @@ def _build_group_prompt(state: WizardState, group_id: str) -> Prompt:
 
 
 def _is_lone_choice_pick(prompt: Prompt) -> bool:
-    """고를 것이 한 줄뿐인 단일 선택 픽인가.
+    """고를 것이 한 줄뿐인 픽인가 — 단일 선택이든 체크박스든.
 
     호스트 선택기는 옵션 2개 미만을 받지 않아(`nativeLimits` `minOptions`) 이런
     화면은 번호 1개짜리 목록으로 내려간다 — 사용자는 고를 것이 없는 목록에서
@@ -106,7 +106,6 @@ def _is_lone_choice_pick(prompt: Prompt) -> bool:
     """
     return (
         prompt.kind == "pick"
-        and not prompt.multi
         and len(prompt.options) == 1
         and prompt.options[0].value != _ABORT_OPTION
     )

package/runtime/skills/okstra-manager/SKILL.md

@@ -29,7 +29,7 @@ okstra manager task status --manager-id <manager-id> --task-group <task-group> -
 okstra manager task sync --manager-id <manager-id> --task-group <task-group> --task-id <task-id>
 okstra manager task assign --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <child-task-id>] [--role <role>] [--tag <tag>] [--assignment <text>]
 okstra manager task note --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --scope <shared|project> [--project-id <project-id>] --body <text>
-okstra manager task run --manager-id <manager-id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--child-task-id <child-task-id>]
+okstra manager task run --manager-id <manager-id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--child-task-id <child-task-id>] [--allow-completed]
 okstra manager task split --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --plan <split-plan.json> [--overwrite]
 okstra manager list managers
 okstra manager list projects --manager-id <manager-id>
@@ -104,7 +104,7 @@ When the user wants to see a manager at a glance, run `okstra manager task sync
 For launching child work:
 
 1. Run `okstra manager task sync ...` if the manager snapshot must be refreshed first.
-2. Run `okstra manager task run ...`.
+2. Run `okstra manager task run ...`. It re-reads the child's state from its project, not from the snapshot. When the child is already done there (terminal next phase, or work status `done`), it refuses with the last phase and report path; tell the user that and do not add `--allow-completed` unless the user asks to run the child again.
 3. Read the returned fixed fields `Backend`, `Worker dispatch backend`, `Project root`, `Context path`, `Run command`, every numbered `Run arg N`, and `Shell command`.
 4. Give the user the `Shell command` line verbatim and tell them to run it in a new terminal. It starts the installed launcher in the child project: the launcher fills the task type and brief from the child task manifest or asks for them, prepares the run with the manager context directive, and starts the child lead as a separate host process (`Backend` `spawn-process`).