okstra 0.6.1 → 0.8.0

package/runtime/python/lib/okstra/usage.sh

@@ -3,7 +3,7 @@
 usage() {
   cat >&2 <<USAGE_EOF
 usage:
-  $DISPLAY_COMMAND_NAME [--render-only] [--yes] [--refresh-assets] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--gemini-model <model>] [--report-writer-model <model>] [--related-tasks taskA,taskB] --project-id <project-id> [--project-root <path>] --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>]
+  $DISPLAY_COMMAND_NAME [--render-only] [--yes] [--refresh-assets] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--gemini-model <model>] [--report-writer-model <model>] [--executor claude|codex|gemini] [--related-tasks taskA,taskB] --project-id <project-id> [--project-root <path>] --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>]
 
 summary:
   $DISPLAY_TOOL_NAME prepares a task-keyed instruction bundle for Claude Code and launches an interactive Claude session by default.
@@ -15,7 +15,7 @@ summary:
   permissions are injected via 'claude --settings' at launch time.
 
 required arguments:
-  --project-id         Globally unique project ID. Example: fontradar-v2-api.
+  --project-id         Globally unique project ID. Example: sample-project-v2-api.
                        Each project is registered at <project-root>/.project-docs/okstra/project.json
                        on first run; subsequent runs verify the projectId there matches.
   --task-group         Logical task group. Example: backend-api, bugfix, linear-8858
@@ -39,6 +39,12 @@ optional arguments:
                        should prefer --resume-clarification, which wraps this flag.
   --approved-plan      Path to the approved final-report.md from a prior implementation-planning run.
                        Required when --task-type=implementation; the file MUST contain a recorded user approval marker.
+  --approve            Treat the user's CLI invocation itself as the plan-approval signal. Only meaningful
+                       together with --approved-plan and --task-type=implementation. The runtime updates the
+                       top "User Approval Request" block of the approved-plan file: flips
+                       \`- [ ] Approved\` to \`- [x] Approved\` and appends an approval audit line
+                       (timestamp + "CLI --approve"). Use this for scripted/CI flows or when you want a
+                       single command to both approve and launch the next phase.
   --task-key <project-id:task-group:task-id>
                        Shorthand for --project-id/--task-group/--task-id. When the matching task-manifest.json
                        exists, brief-path and task-type are auto-filled from it (taskBriefPath and
@@ -66,7 +72,17 @@ options:
   --gemini-model       Model for Gemini worker. Default: OKSTRA_DEFAULT_GEMINI_MODEL or auto
   --report-writer-model
                       Model for report writer worker. Default: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or lead model default
+  --executor           Provider that performs the Executor role during --task-type=implementation.
+                      One of: claude | codex | gemini. Default: OKSTRA_DEFAULT_EXECUTOR or claude.
+                      The Executor is the only worker allowed to mutate project files; the other two
+                      providers are dispatched as read-only verifiers regardless of this selection.
+                      Has no effect on other task types.
   --related-tasks      Optional comma-separated related task identifiers. Example: auth-token-refresh,frontend-login-ui
+  --work-category      Work-category classification for this task. One of:
+                       bugfix | feature | refactor | ops | improvement | unknown.
+                       Defaults to 'unknown' when omitted. Use this when the
+                       lifecycle skipped --task-type=requirements-discovery
+                       (where work-category would otherwise be inferred).
   --task-type          Set the task purpose for this run and select the matching profile file.
   -h, --help           Show this help.
 
@@ -76,6 +92,7 @@ model defaults:
   Claude worker: OKSTRA_DEFAULT_CLAUDE_MODEL or sonnet
   Codex worker: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.5
   Gemini worker: OKSTRA_DEFAULT_GEMINI_MODEL or auto
+  Implementation executor: OKSTRA_DEFAULT_EXECUTOR or claude (one of: claude | codex | gemini)
 
 output:
   Stable task bundles are stored under:

package/runtime/python/okstra_ctl/render.py

@@ -438,10 +438,19 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
     if current_phase:
         phase_states[current_phase] = current_phase_state
     work_category = existing.get("workCategory") or ctx.get("WORKFLOW_WORK_CATEGORY", "unknown")
-    next_recommended_phase = (
-        workflow.get("nextRecommendedPhase")
-        or default_next_phase.get(current_phase, ctx.get("WORKFLOW_NEXT_RECOMMENDED_PHASE", "unknown"))
+    # Compute the canonical next phase from current_phase deterministically.
+    # Only preserve `existing.workflow.nextRecommendedPhase` when it is a
+    # legitimate forward pointer — i.e. NOT equal to `current_phase` itself
+    # (which would mean the lifecycle pointer has stalled on the current
+    # phase and would loop forever).
+    canonical_next = default_next_phase.get(
+        current_phase, ctx.get("WORKFLOW_NEXT_RECOMMENDED_PHASE", "unknown")
     )
+    existing_next = workflow.get("nextRecommendedPhase") or ""
+    if existing_next and existing_next != current_phase:
+        next_recommended_phase = existing_next
+    else:
+        next_recommended_phase = canonical_next
     last_completed_phase = workflow.get("lastCompletedPhase") or ctx.get("WORKFLOW_LAST_COMPLETED_PHASE", "")
     routing_status = workflow.get("routingStatus") or ctx.get("WORKFLOW_ROUTING_STATUS", "not-applicable")
     awaiting_approval = workflow.get("awaitingApproval")
@@ -681,6 +690,14 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
             "disallowLeadSoloAnalysisAsWorkerResult": True,
             "disallowGenericParallelOnlyExecution": True,
             "preferredCompletedWorkerResults": len(reviewers),
+            "executor": {
+                "provider": ctx.get("EXECUTOR_PROVIDER", ""),
+                "displayName": ctx.get("EXECUTOR_DISPLAY_NAME", ""),
+                "workerAgent": ctx.get("EXECUTOR_WORKER_AGENT", ""),
+                "model": ctx.get("EXECUTOR_MODEL_DISPLAY", ""),
+                "modelExecutionValue": ctx.get("EXECUTOR_MODEL_EXECUTION_VALUE", ""),
+                "appliesTo": "implementation",
+            },
         },
         "validation": {
             "required": True,
@@ -857,6 +874,59 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
     _write_text(Path(output_path), rendered.rstrip() + "\n")
 
 
+# --------------------------------------------------------------------------- #
+# Available MCP servers block
+# --------------------------------------------------------------------------- #
+
+
+_NO_MCP_SERVERS_LINE = (
+    "- No MCP servers are declared in `.project-docs/okstra/project.json`'s "
+    "`mcpServers` array. Treat MCP tools as unavailable for this run. To enable "
+    "them, add entries shaped `{name, description, tools, notes?}` to that array "
+    "and re-render the bundle."
+)
+
+
+def build_available_mcp_servers_block(project_root: Path) -> str:
+    """Render the `## Available MCP Servers` first bullet from project.json.
+
+    The MCP server list used to be hardcoded for one specific environment.
+    It now comes from the project's `.project-docs/okstra/project.json`
+    (`mcpServers` array), so each user/project declares the MCP surface
+    available to their lead+workers. Missing file or empty array yields a
+    generic "none declared" fallback.
+    """
+    config_path = project_root / ".project-docs" / "okstra" / "project.json"
+    try:
+        raw = json.loads(config_path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError):
+        return _NO_MCP_SERVERS_LINE
+    servers = raw.get("mcpServers") if isinstance(raw, dict) else None
+    if not isinstance(servers, list) or not servers:
+        return _NO_MCP_SERVERS_LINE
+    lines: list[str] = []
+    for entry in servers:
+        if not isinstance(entry, dict):
+            continue
+        name = str(entry.get("name", "")).strip()
+        if not name:
+            continue
+        description = str(entry.get("description", "")).strip()
+        tools = entry.get("tools") or []
+        notes = str(entry.get("notes", "")).strip()
+        parts = [f"`mcp__{name}`"]
+        if description:
+            parts.append(description)
+        if isinstance(tools, list) and tools:
+            tool_names = ", ".join(f"`{str(t).strip()}`" for t in tools if str(t).strip())
+            if tool_names:
+                parts.append(f"Tools: {tool_names}")
+        if notes:
+            parts.append(notes)
+        lines.append("- " + ". ".join(parts) + ".")
+    return "\n".join(lines) if lines else _NO_MCP_SERVERS_LINE
+
+
 # --------------------------------------------------------------------------- #
 # launch.template.md rendering
 # --------------------------------------------------------------------------- #
@@ -1003,6 +1073,10 @@ def render_template_file(template_path: str, output_path: str, ctx: dict) -> Non
         "{{WORKFLOW_NEXT_RECOMMENDED_PHASE}}": ctx.get("WORKFLOW_NEXT_RECOMMENDED_PHASE", ""),
         "{{PHASE_ALLOWED_OUTPUTS}}": ctx.get("PHASE_ALLOWED_OUTPUTS", ""),
         "{{PHASE_FORBIDDEN_ACTIONS}}": ctx.get("PHASE_FORBIDDEN_ACTIONS", ""),
+        "{{AVAILABLE_MCP_SERVERS}}": ctx.get(
+            "AVAILABLE_MCP_SERVERS",
+            build_available_mcp_servers_block(Path(ctx.get("PROJECT_ROOT", "."))),
+        ),
     }
     rendered = template
     for k, v in mapping.items():

package/runtime/python/okstra_ctl/run.py

@@ -21,6 +21,7 @@ import re
 import shutil
 import subprocess
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
@@ -55,7 +56,7 @@ from .workers import normalize_workers, resolve_profile_workers
 from .workflow import compute_workflow_state
 
 APPROVED_PLAN_PATTERN = re.compile(
-    r"^[ \t]*(APPROVED([ \t]|:|$)|\[x\][ \t]*Approved|"
+    r"^[ \t]*(?:[-*+][ \t]+)?(APPROVED([ \t]|:|$)|\[x\][ \t]*Approved|"
     r"User[ \t]+Approval[ \t]*:[ \t]*(APPROVED|granted|yes))",
     re.IGNORECASE | re.MULTILINE,
 )
@@ -81,11 +82,14 @@ class PrepareInputs:
     codex_model: str = ""
     gemini_model: str = ""
     report_writer_model: str = ""
+    executor: str = ""
     related_tasks_raw: str = ""
+    work_category: str = ""
     approved_plan_path: str = ""
     clarification_response_path: str = ""  # absolute or empty
     render_only: bool = False
     refresh_assets: bool = False
+    approve_plan_ack: bool = False
 
 
 @dataclass
@@ -107,11 +111,65 @@ def _validate_approved_plan(path: str) -> None:
     if not APPROVED_PLAN_PATTERN.search(p.read_text(encoding="utf-8", errors="replace")):
         raise PrepareError(
             f"approved plan has no recognised user-approval marker: {path}\n"
-            '  expected one of (case-insensitive, line-anchored): "APPROVED", '
-            '"[x] Approved", "User Approval: APPROVED|granted|yes"'
+            '  canonical form (single line, top-of-report block): "- [x] Approved"\n'
+            '  also accepted (case-insensitive, line-anchored, optional leading bullet): '
+            '"APPROVED", "[x] Approved", "User Approval: APPROVED|granted|yes"\n'
+            "  shortcut: re-run okstra with --approve to have the CLI itself "
+            "record the approval marker on this file."
         )
 
 
+# `- [ ] Approved` 라인을 정확히 한 번만 매치한다. 좌측 leading whitespace 와
+# 옵션 bullet 은 보존된 채 체크박스 안쪽 공백만 `x` 로 갱신된다.
+APPROVAL_UNCHECKED_PATTERN = re.compile(
+    r"^([ \t]*(?:[-*+][ \t]+)?)\[[ \t]\][ \t]*Approved[ \t]*$",
+    re.IGNORECASE | re.MULTILINE,
+)
+
+
+def _apply_cli_approval(path: str) -> str:
+    """`--approve` 가 지정된 경우 approved-plan 파일에 사용자 승인 마커를 새겨 넣는다.
+
+    Returns a short human-readable description of the action taken (used in the
+    runtime audit line). Idempotent: if the file already carries a valid
+    approval marker, no edits are written and `"already-approved"` is returned.
+    """
+    p = Path(path)
+    if not p.is_file():
+        raise PrepareError(f"approved plan file not found: {path}")
+    body = p.read_text(encoding="utf-8", errors="replace")
+
+    audit_iso = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    audit_line = (
+        f"- 승인 일시 (CLI ack): {audit_iso} — recorded by `okstra --approve` "
+        "(user CLI invocation treated as approval signal)"
+    )
+
+    if APPROVED_PLAN_PATTERN.search(body):
+        # 이미 사용자(또는 이전 --approve 호출)가 마커를 남긴 상태. audit 라인이
+        # 없으면 보조적으로 한 줄만 추가하고 마커 자체는 건드리지 않는다.
+        if audit_line.split(" — ")[1] in body:
+            return "already-approved"
+        new_body = body.rstrip("\n") + "\n" + audit_line + "\n"
+        p.write_text(new_body, encoding="utf-8")
+        return "already-approved-audit-appended"
+
+    if APPROVAL_UNCHECKED_PATTERN.search(body):
+        new_body, count = APPROVAL_UNCHECKED_PATTERN.subn(
+            lambda m: f"{m.group(1)}[x] Approved", body, count=1,
+        )
+        new_body = new_body.rstrip("\n") + "\n" + audit_line + "\n"
+        p.write_text(new_body, encoding="utf-8")
+        return "checkbox-flipped"
+
+    raise PrepareError(
+        f"--approve was given but the approved-plan file has no `User Approval Request` "
+        f"checkbox to flip: {path}\n"
+        "  expected a line of the form `- [ ] Approved` near the top of the report "
+        "(see templates/reports/final-report.template.md)."
+    )
+
+
 def _ensure_task_directories(ctx: dict) -> None:
     for key in (
         "TASK_ROOT", "INSTRUCTION_SET_DIR", "RUNS_DIR", "HISTORY_DIR",
@@ -265,7 +323,9 @@ def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
         ("--codex-model", inp.codex_model or ctx.get("CODEX_WORKER_MODEL_DISPLAY", "")),
         ("--gemini-model", inp.gemini_model or ctx.get("GEMINI_WORKER_MODEL_DISPLAY", "")),
         ("--report-writer-model", inp.report_writer_model or ctx.get("REPORT_WRITER_MODEL_DISPLAY", "")),
+        ("--executor", inp.executor or ctx.get("EXECUTOR_PROVIDER", "")),
         ("--related-tasks", inp.related_tasks_raw),
+        ("--work-category", inp.work_category),
     ]
     argv: list[str] = []
     for flag, val in pairs:
@@ -328,7 +388,19 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
             raise PrepareError(
                 "task-type implementation requires --approved-plan <path-to-final-report.md>"
             )
+        if inp.approve_plan_ack:
+            # 사용자가 직접 `--approve` 를 입력한 행위 자체를 승인 의사로 모델링한다.
+            # 파일을 먼저 갱신한 뒤 동일한 검증 경로를 그대로 통과시킨다 — 검증
+            # 책임을 단일 지점(`_validate_approved_plan`)으로 유지한다.
+            _apply_cli_approval(inp.approved_plan_path)
         _validate_approved_plan(inp.approved_plan_path)
+    elif inp.approve_plan_ack:
+        # implementation 외 task-type 에서 `--approve` 는 의미가 없다. 사용자에게
+        # 정확한 시점을 알려주기 위해 조용히 무시하지 않고 즉시 거부한다.
+        raise PrepareError(
+            "--approve is only meaningful with --task-type implementation "
+            "and --approved-plan <path>"
+        )
     if inp.clarification_response_path and not Path(inp.clarification_response_path).is_file():
         raise PrepareError(
             f"clarification response file not found: {inp.clarification_response_path}"
@@ -383,6 +455,22 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         default_display=report_writer_default, default_execution=report_writer_default,
     )
 
+    # ---- executor binding (implementation phase only; recorded universally for manifest consistency) ----
+    executor_default = _default("OKSTRA_DEFAULT_EXECUTOR", "claude")
+    executor_provider = (inp.executor or executor_default).strip().lower()
+    if executor_provider not in ("claude", "codex", "gemini"):
+        raise PrepareError(
+            f"--executor must be one of: claude, codex, gemini (got: {executor_provider!r})"
+        )
+    executor_provider_to_meta = {
+        "claude": ("Claude executor", "claude-worker", cw),
+        "codex": ("Codex executor", "codex-worker", co),
+        "gemini": ("Gemini executor", "gemini-worker", ge),
+    }
+    executor_display_name, executor_worker_agent, executor_model_meta = (
+        executor_provider_to_meta[executor_provider]
+    )
+
     # ---- paths under per-task mutex (writes run-context-*.json) ----
     # OKSTRA_RUN_SEQ_OVERRIDE: okstra-ctl rerun / 테스트 hook 이 미리 reserve
     # 한 seq 를 강제하는 user-knob 환경 변수.
@@ -444,6 +532,11 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "GEMINI_WORKER_MODEL_EXECUTION_VALUE": ge.execution,
         "REPORT_WRITER_MODEL_DISPLAY": rw.display,
         "REPORT_WRITER_MODEL_EXECUTION_VALUE": rw.execution,
+        "EXECUTOR_PROVIDER": executor_provider,
+        "EXECUTOR_DISPLAY_NAME": executor_display_name,
+        "EXECUTOR_WORKER_AGENT": executor_worker_agent,
+        "EXECUTOR_MODEL_DISPLAY": executor_model_meta.display,
+        "EXECUTOR_MODEL_EXECUTION_VALUE": executor_model_meta.execution,
         "RELATED_TASKS_JSON": related_tasks_json_str,
         "RELATED_TASKS_BULLETS": bullets,
         "RELATED_TASKS_INLINE": inline,
@@ -464,16 +557,29 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     cleanup_obsolete_generated_docs(
         project_root=project_root, instruction_set_dir=Path(ctx["INSTRUCTION_SET_DIR"]),
     )
-    if not inp.render_only:
-        write_claude_resume_command_file(
-            resume_command_path=Path(ctx["CLAUDE_RESUME_COMMAND_FILE"]),
-            project_root=project_root, claude_session_id=claude_session_id,
-        )
+    # Always materialise the resume command script. Even in --render-only
+    # preparation flows the user (or a later non-interactive runner) may
+    # invoke it manually; deferring its creation until interactive launch
+    # leaves runs/<phase>/sessions/ empty and the manifest pointing at a
+    # path that does not exist.
+    write_claude_resume_command_file(
+        resume_command_path=Path(ctx["CLAUDE_RESUME_COMMAND_FILE"]),
+        project_root=project_root, claude_session_id=claude_session_id,
+    )
 
     # ---- write instruction-set scaffolding ----
     instruction_set = Path(ctx["INSTRUCTION_SET_DIR"])
     instruction_set.mkdir(parents=True, exist_ok=True)
-    (instruction_set / "analysis-profile.md").write_text(profile_content, encoding="utf-8")
+    profile_rendered = profile_content
+    for key in (
+        "EXECUTOR_PROVIDER",
+        "EXECUTOR_DISPLAY_NAME",
+        "EXECUTOR_WORKER_AGENT",
+        "EXECUTOR_MODEL_DISPLAY",
+        "EXECUTOR_MODEL_EXECUTION_VALUE",
+    ):
+        profile_rendered = profile_rendered.replace("{{" + key + "}}", ctx.get(key, ""))
+    (instruction_set / "analysis-profile.md").write_text(profile_rendered, encoding="utf-8")
     (instruction_set / "analysis-material.md").write_text(review_material, encoding="utf-8")
     shutil.copyfile(inp.brief_path, instruction_set / "task-brief.md")
     if inp.clarification_response_path:
@@ -512,6 +618,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
             "codexModel": co.display,
             "geminiModel": ge.display,
             "reportWriterModel": rw.display,
+            "executor": executor_provider,
             "relatedTasks": inp.related_tasks_raw,
             "approvedPlanPath": inp.approved_plan_path,
             "clarificationResponsePath": inp.clarification_response_path,
@@ -536,6 +643,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         current_run_status=ctx["CURRENT_RUN_STATUS"],
         current_task_status=ctx["CURRENT_TASK_STATUS"],
         render_only=inp.render_only,
+        work_category=inp.work_category,
     ))
     render_team_state(ctx["TEAM_STATE_FILE"], ctx)
     render_task_manifest(ctx["TASK_MANIFEST_FILE"], ctx)
@@ -603,11 +711,32 @@ def main(argv: list[str]) -> int:
     p.add_argument("--codex-model", default="")
     p.add_argument("--gemini-model", default="")
     p.add_argument("--report-writer-model", default="")
+    p.add_argument("--executor", default="")
     p.add_argument("--related-tasks", default="", dest="related_tasks_raw")
     p.add_argument("--approved-plan", default="", dest="approved_plan_path")
+    p.add_argument(
+        "--approve",
+        action="store_true",
+        dest="approve_plan_ack",
+        help=(
+            "Treat the CLI invocation itself as the plan approval signal. "
+            "Flips `- [ ] Approved` to `- [x] Approved` in the --approved-plan file "
+            "and appends an audit line."
+        ),
+    )
     p.add_argument("--clarification-response", default="", dest="clarification_response_path")
     p.add_argument("--render-only", action="store_true", dest="render_only")
     p.add_argument("--refresh-assets", action="store_true", dest="refresh_assets")
+    p.add_argument(
+        "--work-category",
+        default="",
+        dest="work_category",
+        help=(
+            "Work-category classification for this task "
+            "(bugfix / feature / refactor / ops / improvement). "
+            "Falls back to `unknown` when omitted."
+        ),
+    )
     args = p.parse_args(argv)
 
     project_root = Path(args.project_root).expanduser().resolve()
@@ -641,11 +770,14 @@ def main(argv: list[str]) -> int:
         codex_model=args.codex_model,
         gemini_model=args.gemini_model,
         report_writer_model=args.report_writer_model,
+        executor=args.executor,
         related_tasks_raw=args.related_tasks_raw,
+        work_category=args.work_category,
         approved_plan_path=args.approved_plan_path,
         clarification_response_path=clarification_abs,
         render_only=args.render_only,
         refresh_assets=args.refresh_assets,
+        approve_plan_ack=args.approve_plan_ack,
     )
     try:
         out = prepare_task_bundle(inputs)

package/runtime/python/okstra_ctl/workflow.py

@@ -138,6 +138,7 @@ def compute_workflow_state(
     current_run_status: str,
     current_task_status: str,
     render_only: bool,
+    work_category: str = "",
 ) -> dict:
     """WORKFLOW_* + PHASE_* 값을 dict 로 돌려준다."""
     if current_run_status == "in-progress":
@@ -170,8 +171,10 @@ def compute_workflow_state(
     rules = PHASE_RULES.get(task_type, PHASE_RULES_UNKNOWN)
     last_completed = task_type if current_run_status == "completed" else ""
 
+    resolved_work_category = (work_category or "").strip() or "unknown"
+
     return {
-        "WORKFLOW_WORK_CATEGORY": "unknown",
+        "WORKFLOW_WORK_CATEGORY": resolved_work_category,
         "WORKFLOW_CURRENT_PHASE": task_type,
         "WORKFLOW_CURRENT_PHASE_STATE": phase_state,
         "WORKFLOW_NEXT_RECOMMENDED_PHASE": default_next_phase_for(task_type),

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

@@ -103,6 +103,7 @@ To re-run a specific run:
    - `recommendedWorkers` → `--workers` (comma-separated)
    - `relatedTasks` → `--related-tasks` (if present)
    - model overrides → `--claude-model`, `--codex-model`, `--gemini-model` (if different from default)
+   - for `taskType: implementation`: `teamContract.executor.provider` → `--executor <claude|codex|gemini>` (if different from `claude`)
 4. Display the assembled command:
 
 ```bash

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

@@ -128,8 +128,9 @@ Validate that slugified `task_group` and `task_id` each contain at least one alp
 
 For existing tasks, present `nextRecommendedPhase` as the first option (recommended default).
 
-If `implementation` chosen, ask one more `AskUserQuestion`:
+If `implementation` chosen, ask two more `AskUserQuestion` in order:
 - `"Path to the approved final-report.md (must contain APPROVED marker)"` — the underlying python `prepare_task_bundle` re-validates the marker, but you can pre-check with `grep`.
+- `"Executor provider for this run (claude | codex | gemini)?"` — only this provider mutates project files; the other two run as read-only verifiers. Default `claude` (or `OKSTRA_DEFAULT_EXECUTOR` if set). Pass the answer through `PrepareInputs.executor`.
 
 ## Step 5: Brief path
 
@@ -176,6 +177,7 @@ out = prepare_task_bundle(PrepareInputs(
     lead_model="...", claude_model="...", codex_model="...",
     gemini_model="...", report_writer_model="...",
     related_tasks_raw="...",
+    executor="<claude|codex|gemini or empty>",  # implementation only; empty → default (claude / OKSTRA_DEFAULT_EXECUTOR)
     approved_plan_path="<approved-plan-or-empty>",
     clarification_response_path=str(clarification_abs) if clarification_abs else "",
     render_only=True,

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

@@ -96,7 +96,7 @@ so overwriting requires manually deleting the file first.
 
 If the file does NOT exist, ask via `AskUserQuestion`:
 
-- **Question**: `"Project id for okstra (e.g. INV-1234, fontsninja, okstra)"`
+- **Question**: `"Project id for okstra (e.g. INV-1234, my-app, okstra)"`
 - **Validate**: slugified must contain at least one alphanumeric character.
 
 Then create the file:

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

@@ -43,7 +43,7 @@ Extract the following fields from each task.
 |------|------|
 | `taskKey` | `<project-id>:<task-group>:<task-id>` |
 | `taskType` | latest task type |
-| `workCategory` | bugfix / feature / improvement / refactor / ops-change / unknown |
+| `workCategory` | bugfix / feature / improvement / refactor / ops-change / unknown. Display `unknown` as-is, but flag with `(unset)` annotation so the reader knows the requirements-discovery classification was skipped or no `--work-category` flag was passed. |
 | `currentStatus` | task-level status |
 | `currentPhase` | lifecycle current phase |
 | `currentPhaseState` | lifecycle phase state |
@@ -213,7 +213,16 @@ Accepted `<status>` values: `todo`, `in-progress`, `blocked`, `done`.
 
 ### Default Value Convention
 
-If `workStatus` is missing or empty in any manifest, treat it as `in-progress` for read purposes. Do not back-fill the field on read; only write it when the user explicitly issues an update.
+If `workStatus` is missing or empty in any manifest, infer the display value from the lifecycle state — DO NOT default to a static `in-progress`:
+
+| Manifest state | Inferred display |
+|---|---|
+| `currentStatus == "completed"` AND `workflow.nextRecommendedPhase` in (`done-or-follow-up`, empty) | `done` (inferred) |
+| `currentStatus == "completed"` AND `workflow.currentPhaseState == "completed"` | `phase-done` (inferred) |
+| `currentStatus == "contract-violated"` OR `workflow.currentPhaseState == "blocked"` | `blocked` (inferred) |
+| anything else | `in-progress` (default) |
+
+Annotate inferred values with `(inferred)` or `(default)` in the rendered output so the reader can see which value is user-set vs. system-inferred. Do not back-fill the field on read; only write it when the user explicitly issues an update.
 
 ### Catalog Sync Note
 

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -42,6 +42,7 @@ Only workers selected from `recommendedWorkers` in `task-manifest.json` and `res
 
 ## Operating Rules
 
+0. **TeamCreate ordering (BLOCKING).** Before issuing any `Agent` dispatch that includes `team_name`, Lead MUST have called `TeamCreate(team_name: "okstra-<task-key>", ...)` in this run and recorded the outcome in team-state as `teamCreate: { attempted: true, status: "ok"|"error", error?: <message> }`. If the Agent tool rejects a dispatch with `"team must be created first or call without team_name"` / `"team을 먼저 생성하거나 team_name 없이 호출해야 합니다"`, the correct response is to go back to Phase 3 and call `TeamCreate` — NOT to strip `team_name` and retry. The no-`team_name` Phase 5 fallback is only legal when `teamCreate.status == "error"` is already recorded; otherwise stripping `team_name` silently degrades the run to in-process background dispatch and loses the Teams split-pane behavior. See [okstra agent SKILL.md Phase 3](../../agents/SKILL.md) for the full team-creation sequence.
 1. `Claude lead` is responsible for orchestration, convergence supervision, and final-report review/approval. It never overrides worker analysis results, and it never authors the final-report file when `Report writer worker` is in the roster.
 2. `Report writer worker` is NOT an analysis worker. It is excluded from Phase 4/5 (initial analysis) and Phase 5.5 (convergence re-verification). It is spawned only in Phase 6 and is the **author** of the final-report file at `runs/<task-type>/reports/final-report-<task-type>-<seq>.md`.
 3. When `Report writer worker` is in the roster, Lead MUST dispatch it in Phase 6. The only legal lead-authored fallback is when a dispatch was attempted and recorded a terminal status of `error` / `timeout` / `not-run` with a concrete logged reason. Speculative reasons such as "session resume constraint" or "team is no longer alive" are NOT valid — Lead can always dispatch a fresh subagent (omit `team_name` if the team is gone).

package/runtime/templates/reports/final-report.template.md

@@ -6,6 +6,18 @@
 - Lead Model: `{{LEAD_MODEL}}`
 - Clarification Response Carried In: `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}`
 
+## User Approval Request (사용자 승인 게이트)
+
+> **이 블록은 `task-type` = `implementation-planning` 결과에서만 의미를 가집니다.** 다른 task-type의 보고서에서는 이 섹션 전체를 삭제하세요.
+>
+> 다음 `implementation` run은 아래 체크박스가 `[x]`로 표시되어 있을 때에만 진입할 수 있습니다 (`okstra_ctl.run._validate_approved_plan` 가 이 마커를 line-anchored 정규식으로 검사하여 통과/거부합니다). 본문(`Sections 1`–`4.5`)을 끝까지 읽고, `4.5.9 Open Questions`가 비어 있거나 모두 해소된 뒤 승인해 주세요.
+
+- 승인 여부 (사용자가 직접 편집): `- [ ] Approved` ← 승인하려면 `[ ]` 를 `[x]` 로 변경하여 저장하세요.
+- 승인 후 다음 단계 명령어 (방법 A — 수동 편집): `okstra --task-key {{TASK_KEY}} --task-type implementation --approved-plan <이 보고서 경로>`
+- 승인 + 실행 한 번에 (방법 B — CLI 자체를 승인 의사로): `okstra --task-key {{TASK_KEY}} --task-type implementation --approved-plan <이 보고서 경로> --approve`
+  - 방법 B 는 `--approve` 입력 행위 자체를 승인 의사로 모델링합니다. 런타임이 본 블록의 체크박스를 자동으로 `[x]` 로 바꾸고, 본 섹션 하단에 `승인 일시 (CLI ack): <ISO8601>` audit 라인을 한 줄 덧붙입니다.
+- 승인을 보류하거나 거부하려면 체크박스는 `[ ]` 로 두고 `--approve` 도 사용하지 마세요. 필요한 변경 사항은 `4.5.9 Open Questions` 또는 `Section 5 Clarification Requests` 에 기록한 뒤 같은 phase 를 재실행해 주세요.
+
 ## 0. Clarification Response Carried In From Previous Run
 - Source file: `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}`
 - If the source path is empty, write `- No prior clarification response was provided for this run.` and skip the rest of this section.
@@ -89,9 +101,9 @@
 ### 4.5.7 Rollback Strategy (롤백 전략)
 - 정확한 revert 경로(commits, flags, migrations 등)와 롤백을 트리거하는 신호(에러율, latency, 사용자 보고 등)를 명시합니다.
 
-### 4.5.8 User Approval Request (사용자 승인 요청)
-- 다음 `implementation` run을 시작해도 되는지에 대한 명시적 승인 요청 블록입니다. 사용자가 명시적으로 승인하기 전까지는 이 plan을 코드로 옮기지 않습니다.
-- 승인 시 사용할 명령어 한 줄을 함께 적습니다: `okstra --task-key {{TASK_KEY}} --task-type implementation --approved-plan <이 보고서 경로>`
+### 4.5.8 User Approval Request (사용자 승인 요청 — 본 보고서 상단 참조)
+- 실제 승인 게이트는 본 보고서 **상단 `User Approval Request (사용자 승인 게이트)` 블록**에 있습니다. 이 하위 섹션은 validator가 요구하는 영문 키워드(`User Approval Request`)와 본문 구조 일관성을 위해 남겨 둡니다.
+- 본 섹션에는 승인 결정에 영향을 주는 *플랜 측 보충 메모*만 적습니다(예: 위험을 줄이기 위한 사전 작업, 승인 전 사용자가 확인해 두어야 할 사항). 승인 마커는 본 섹션이 아니라 상단 블록의 체크박스로만 부여합니다.
 
 ### 4.5.9 Open Questions
 - pre-planning에서 발견된 모든 모호점을 항목으로 남겨, 사용자가 승인 전에 해소해야 할 질문 목록으로 사용합니다.

package/runtime/templates/reports/settings.template.json

@@ -83,19 +83,7 @@
       "Bash(curl:*)",
       "Bash(wget:*)",
       "mcp__test-context7__resolve-library-id",
-      "mcp__test-context7__query-docs",
-      "mcp__mysql-fontsninja-common__mysql_list_tables",
-      "mcp__mysql-fontsninja-common__mysql_describe_table",
-      "mcp__mysql-fontsninja-common__mysql_select_data",
-      "mcp__mysql-fontsninja-fontradar__mysql_list_tables",
-      "mcp__mysql-fontsninja-fontradar__mysql_describe_table",
-      "mcp__mysql-fontsninja-fontradar__mysql_select_data",
-      "mcp__mysql-fontsninja-fontsninja__mysql_list_tables",
-      "mcp__mysql-fontsninja-fontsninja__mysql_describe_table",
-      "mcp__mysql-fontsninja-fontsninja__mysql_select_data",
-      "mcp__mysql-fontsninja-fonthelper__mysql_list_tables",
-      "mcp__mysql-fontsninja-fonthelper__mysql_describe_table",
-      "mcp__mysql-fontsninja-fonthelper__mysql_select_data"
+      "mcp__test-context7__query-docs"
     ]
   }
 }

package/runtime/templates/reports/task-brief.template.md

@@ -127,24 +127,13 @@
 
 ## Available MCP Servers
 
-The following MCP servers are registered at the user scope and may be invoked **as needed** during this run by Claude lead, Claude worker, and Report writer worker. The lead is responsible for forwarding this section verbatim into the worker prompts (Phase 2) so workers know they are allowed to call these tools.
+The MCP servers available to this run are declared in `.project-docs/okstra/project.json`'s `mcpServers` array and rendered into the Claude lead's launch prompt under `## Available MCP Servers`. They may be invoked **as needed** by Claude lead, Claude worker, and Report writer worker. The lead is responsible for forwarding the rendered list verbatim into the worker prompts (Phase 2) so workers know which tools they are allowed to call.
 
-| Server | Backing data | Mode | Typical use |
-|--------|--------------|------|-------------|
-| `mcp__mysql-fontsninja-common` | local Docker MySQL `common` schema | read-only | shared lookups, code list, reference data |
-| `mcp__mysql-fontsninja-fontradar` | local Docker MySQL `fontradar` schema | read-only | fontradar service data inspection |
-| `mcp__mysql-fontsninja-fontsninja` | local Docker MySQL `fontsninja` schema | read-only | fontsninja service data inspection |
-| `mcp__mysql-fontsninja-fonthelper` | local Docker MySQL `fonthelper` schema | read-only | fonthelper service data inspection |
-
-Available tools per server (all read-only — write tools are disabled at the server):
-
-- `mysql_list_tables`
-- `mysql_describe_table`
-- `mysql_select_data`
+To declare servers, add entries shaped `{ "name": "<server>", "description": "...", "tools": ["..."], "notes": "..." }` to that array. If the array is empty or absent, treat MCP as unavailable for this run.
 
 How to invoke (worker-by-worker):
 
-- **Claude lead / Claude worker / Report writer worker**: invoke the MCP tool **directly by its tool name** (e.g. `mcp__mysql-fontsninja-fontsninja__mysql_list_tables`) through the host's tool interface. **Do NOT call it via `Bash`** — these names are MCP tools, not shell commands; running them in a shell will always fail with `command not found` regardless of permission settings.
+- **Claude lead / Claude worker / Report writer worker**: invoke the MCP tool **directly by its tool name** (e.g. `mcp__<server>__<tool>`) through the host's tool interface. **Do NOT call it via `Bash`** — these names are MCP tools, not shell commands; running them in a shell will always fail with `command not found` regardless of permission settings.
 - **Codex worker / Gemini worker**: invoke through the external CLI's own MCP transport (e.g. `codex mcp call <server> <tool> <args>` for Codex CLI; the equivalent Gemini CLI MCP invocation for Gemini). If the worker's CLI has no matching MCP config, treat the server as unavailable for this run and record `MCP not available in this CLI` in `Missing Information or Assumptions` — do **not** attempt a shell fallback such as `mysql -h ...` or piping a tool name into `bash`.
 - All workers: cite the exact server, tool, and SELECT (or `WHERE` filters) used in the result file. Tool-call failures must be logged in the worker's `*-errors.json` (commandKind `mcp_call`) so the lead can decide whether to retry under a different worker.