okstra 0.77.0 → 0.78.0

package/runtime/python/okstra_ctl/doctor.py

@@ -0,0 +1,292 @@
+"""Phase-aware diagnostics for ``okstra doctor --phase``."""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Iterable
+
+from okstra_project import ResolverError, project_json_path, resolve_project_root
+
+from . import improvement_lenses, worktree_registry
+from .workers import resolve_profile_workers
+from .worktree import is_git_work_tree, main_worktree_path
+
+SUPPORTED_PHASES: tuple[str, ...] = (
+    "implementation",
+    "final-verification",
+    "release-handoff",
+    "improvement-discovery",
+)
+
+_BASE_BRANCHES = {"main", "master", "prod", "preprod", "staging", "dev"}
+
+
+@dataclass(frozen=True)
+class DoctorCheck:
+    name: str
+    ok: bool
+    detail: str
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+def phase_diagnostics(
+    phase: str,
+    *,
+    cwd: str | Path,
+    workspace_root: str | Path,
+    home: str | Path,
+) -> dict[str, object]:
+    """Return JSON-serialisable readiness checks for one lifecycle phase."""
+    if phase not in SUPPORTED_PHASES:
+        return {
+            "ok": False,
+            "usageError": True,
+            "reason": _unknown_phase_message(phase),
+            "supportedPhases": list(SUPPORTED_PHASES),
+            "checks": [],
+        }
+
+    workspace = Path(workspace_root)
+    home_path = Path(home)
+    project_root, checks = _project_checks(Path(cwd))
+    checks.append(_profile_check(workspace, phase))
+
+    if project_root is not None:
+        checks.extend(_phase_checks(phase, project_root, workspace, home_path))
+
+    return {
+        "ok": all(check.ok for check in checks),
+        "usageError": False,
+        "phase": phase,
+        "projectRoot": str(project_root) if project_root else "",
+        "checks": [check.to_dict() for check in checks],
+    }
+
+
+def _unknown_phase_message(phase: str) -> str:
+    supported = ", ".join(SUPPORTED_PHASES)
+    return f"unknown phase '{phase}' (expected one of: {supported})"
+
+
+def _project_checks(cwd: Path) -> tuple[Path | None, list[DoctorCheck]]:
+    try:
+        project_root = resolve_project_root(explicit_root="", cwd=str(cwd))
+    except ResolverError as exc:
+        return None, [_fail("project root", str(exc))]
+
+    checks = [_ok("project root", str(project_root))]
+    project_json = project_json_path(project_root)
+    if project_json.is_file():
+        checks.append(_ok("project registration", str(project_json)))
+    else:
+        checks.append(
+            _fail(
+                "project registration",
+                f"{project_json} not found — run okstra setup in this project first",
+            )
+        )
+    return project_root, checks
+
+
+def _profile_check(workspace: Path, phase: str) -> DoctorCheck:
+    profile = _profile_path(workspace, phase)
+    if profile.is_file():
+        return _ok("profile", str(profile))
+    return _fail("profile", f"not found: {profile}")
+
+
+def _phase_checks(
+    phase: str,
+    project_root: Path,
+    workspace: Path,
+    home: Path,
+) -> list[DoctorCheck]:
+    if phase == "implementation":
+        return _implementation_checks(project_root, workspace, home)
+    if phase == "final-verification":
+        return _final_verification_checks(workspace)
+    if phase == "release-handoff":
+        return _release_handoff_checks(project_root)
+    if phase == "improvement-discovery":
+        return _improvement_discovery_checks(workspace, home)
+    return []
+
+
+def _implementation_checks(
+    project_root: Path,
+    workspace: Path,
+    home: Path,
+) -> list[DoctorCheck]:
+    return [
+        _git_work_tree_check(project_root),
+        _git_worktree_support_check(project_root),
+        _approved_plan_validator_check(),
+        _worker_agents_check(home, workspace, "implementation"),
+    ]
+
+
+def _final_verification_checks(workspace: Path) -> list[DoctorCheck]:
+    return [
+        _worktree_registry_check(),
+        _file_check("validation command", workspace / "validators" / "validate-run.py"),
+        _file_check(
+            "final report template",
+            workspace / "templates" / "reports" / "final-report.template.md",
+        ),
+        _file_check(
+            "final report schema",
+            workspace / "schemas" / "final-report-v1.0.schema.json",
+        ),
+    ]
+
+
+def _release_handoff_checks(project_root: Path) -> list[DoctorCheck]:
+    return [
+        _gh_auth_check(project_root),
+        _git_clean_check(project_root),
+        _git_remote_check(project_root),
+        _feature_branch_check(project_root),
+    ]
+
+
+def _improvement_discovery_checks(workspace: Path, home: Path) -> list[DoctorCheck]:
+    return [
+        _worker_agents_check(home, workspace, "improvement-discovery"),
+        _file_check("gemini worker agent", _agent_path(home, "gemini")),
+        _lens_whitelist_check(),
+    ]
+
+
+def _git_work_tree_check(project_root: Path) -> DoctorCheck:
+    if is_git_work_tree(project_root):
+        return _ok("git work tree", str(main_worktree_path(project_root)))
+    return _fail("git work tree", f"{project_root} is not inside a git work tree")
+
+
+def _git_worktree_support_check(project_root: Path) -> DoctorCheck:
+    result = _run(["git", "-C", str(project_root), "worktree", "list", "--porcelain"])
+    if result.returncode == 0:
+        return _ok("git worktree support", "git worktree list succeeded")
+    return _fail("git worktree support", _command_detail(result))
+
+
+def _approved_plan_validator_check() -> DoctorCheck:
+    try:
+        from .run import _validate_approved_plan  # noqa: F401
+    except Exception as exc:
+        return _fail("approved-plan validator", str(exc))
+    return _ok("approved-plan validator", "okstra plan-validate is available")
+
+
+def _worker_agents_check(home: Path, workspace: Path, phase: str) -> DoctorCheck:
+    workers = resolve_profile_workers(_profile_path(workspace, phase))
+    if not workers:
+        return _ok("worker agents", "no worker agents required")
+    missing = [worker for worker in workers if not _agent_path(home, worker).is_file()]
+    roster = ",".join(workers)
+    if missing:
+        return _fail(
+            "worker agents",
+            f"missing {','.join(missing)}; profile requires {roster}",
+        )
+    return _ok("worker agents", f"installed: {roster}")
+
+
+def _worktree_registry_check() -> DoctorCheck:
+    if callable(worktree_registry.lookup) and callable(worktree_registry.task_key):
+        return _ok(
+            "worktree lookup helper",
+            "lookup helper available; target-specific lookup requires a task key",
+        )
+    return _fail("worktree lookup helper", "lookup helper unavailable")
+
+
+def _gh_auth_check(project_root: Path) -> DoctorCheck:
+    result = _run(["gh", "auth", "status"], cwd=project_root)
+    if result.returncode == 0:
+        return _ok("gh auth", "gh auth status succeeded")
+    return _fail("gh auth", _command_detail(result))
+
+
+def _git_clean_check(project_root: Path) -> DoctorCheck:
+    result = _run(["git", "-C", str(project_root), "status", "--short"])
+    if result.returncode != 0:
+        return _fail("git clean tree", _command_detail(result))
+    if result.stdout.strip():
+        return _fail("git clean tree", result.stdout.strip().splitlines()[0])
+    return _ok("git clean tree", "working tree clean")
+
+
+def _git_remote_check(project_root: Path) -> DoctorCheck:
+    result = _run(["git", "-C", str(project_root), "remote", "get-url", "origin"])
+    if result.returncode == 0 and result.stdout.strip():
+        return _ok("git remote", result.stdout.strip())
+    return _fail("git remote", _command_detail(result))
+
+
+def _feature_branch_check(project_root: Path) -> DoctorCheck:
+    result = _run(["git", "-C", str(project_root), "rev-parse", "--abbrev-ref", "HEAD"])
+    branch = result.stdout.strip()
+    if result.returncode != 0 or not branch:
+        return _fail("feature branch", _command_detail(result))
+    if branch == "HEAD":
+        return _fail("feature branch", "detached HEAD")
+    if branch in _BASE_BRANCHES:
+        return _fail("feature branch", f"current branch is base branch: {branch}")
+    return _ok("feature branch", branch)
+
+
+def _lens_whitelist_check() -> DoctorCheck:
+    lenses = improvement_lenses.LENSES
+    if lenses and all(improvement_lenses.is_valid_lens(lens) for lens in lenses):
+        return _ok("lens whitelist", ",".join(lenses))
+    return _fail("lens whitelist", "invalid or empty lens whitelist")
+
+
+def _file_check(name: str, path: Path) -> DoctorCheck:
+    if path.is_file():
+        return _ok(name, str(path))
+    return _fail(name, f"not found: {path}")
+
+
+def _agent_path(home: Path, worker: str) -> Path:
+    return home / ".claude" / "agents" / f"{worker}-worker.md"
+
+
+def _profile_path(workspace: Path, phase: str) -> Path:
+    return workspace / "prompts" / "profiles" / f"{phase}.md"
+
+
+def _run(
+    args: Iterable[str],
+    *,
+    cwd: Path | None = None,
+) -> subprocess.CompletedProcess[str]:
+    try:
+        return subprocess.run(
+            list(args),
+            cwd=str(cwd) if cwd else None,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except (OSError, FileNotFoundError) as exc:
+        return subprocess.CompletedProcess(list(args), 127, "", str(exc))
+
+
+def _command_detail(result: subprocess.CompletedProcess[str]) -> str:
+    output = (result.stderr or result.stdout).strip()
+    if output:
+        return output.splitlines()[-1]
+    return f"command exited {result.returncode}"
+
+
+def _ok(name: str, detail: str) -> DoctorCheck:
+    return DoctorCheck(name=name, ok=True, detail=detail)
+
+
+def _fail(name: str, detail: str) -> DoctorCheck:
+    return DoctorCheck(name=name, ok=False, detail=detail)

package/runtime/python/okstra_ctl/lead_runtime.py

@@ -0,0 +1,72 @@
+"""Lead runtime metadata shared by render and prepare paths."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class LeadRuntimeInfo:
+    runtime: str
+    agent: str
+    agent_label: str
+    role: str
+    adapter_name: str
+    adapter_dispatch_mode: str
+    session_accounting: str
+    has_claude_session: bool
+
+    def adapter_payload(self) -> dict[str, str]:
+        return {
+            "name": self.adapter_name,
+            "dispatchMode": self.adapter_dispatch_mode,
+            "sessionAccounting": self.session_accounting,
+        }
+
+
+ALLOWED_LEAD_RUNTIMES = ("claude-code", "codex", "external")
+ARTIFACT_ONLY_LEAD_RUNTIMES = frozenset({"codex", "external"})
+
+_LEAD_RUNTIMES = {
+    "claude-code": LeadRuntimeInfo(
+        runtime="claude-code",
+        agent="claude",
+        agent_label="Claude Code",
+        role="Claude lead",
+        adapter_name="claude-code",
+        adapter_dispatch_mode="team",
+        session_accounting="claude-jsonl",
+        has_claude_session=True,
+    ),
+    "codex": LeadRuntimeInfo(
+        runtime="codex",
+        agent="codex",
+        agent_label="Codex CLI",
+        role="Codex lead",
+        adapter_name="codex",
+        adapter_dispatch_mode="render-only",
+        session_accounting="artifact-only",
+        has_claude_session=False,
+    ),
+    "external": LeadRuntimeInfo(
+        runtime="external",
+        agent="external",
+        agent_label="External harness",
+        role="Okstra lead",
+        adapter_name="external",
+        adapter_dispatch_mode="render-only",
+        session_accounting="artifact-only",
+        has_claude_session=False,
+    ),
+}
+
+
+def lead_runtime_info(runtime: str) -> LeadRuntimeInfo:
+    try:
+        return _LEAD_RUNTIMES[runtime]
+    except KeyError as exc:
+        allowed = ", ".join(ALLOWED_LEAD_RUNTIMES)
+        raise ValueError(f"unsupported lead runtime: {runtime} (allowed: {allowed})") from exc
+
+
+def is_artifact_only_runtime(runtime: str) -> bool:
+    return runtime in ARTIFACT_ONLY_LEAD_RUNTIMES

package/runtime/python/okstra_ctl/render.py

@@ -28,6 +28,7 @@ from okstra_project.dirs import OKSTRA_DIR_NAME, project_json_path
 # render_task_manifest 가 동일한 리스트/딕셔너리를 로컬에 중복 정의했는데,
 # 이는 silent drift 위험이 있어 SSOT import 로 통합한다.
 from . import fix_cycles
+from .lead_runtime import lead_runtime_info
 from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
 
 
@@ -70,31 +71,24 @@ def _lead_runtime(ctx: dict) -> str:
     return ctx.get("LEAD_RUNTIME", "") or "claude-code"
 
 
+def _lead_info(ctx: dict):
+    return lead_runtime_info(_lead_runtime(ctx))
+
+
 def _lead_agent(ctx: dict) -> str:
-    return "codex" if _lead_runtime(ctx) == "codex" else "claude"
+    return _lead_info(ctx).agent
 
 
 def _lead_agent_label(ctx: dict) -> str:
-    return "Codex CLI" if _lead_runtime(ctx) == "codex" else "Claude Code"
+    return _lead_info(ctx).agent_label
 
 
 def _lead_role(ctx: dict) -> str:
-    return "Codex lead" if _lead_runtime(ctx) == "codex" else "Claude lead"
+    return _lead_info(ctx).role
 
 
 def _lead_adapter(ctx: dict) -> dict:
-    runtime = _lead_runtime(ctx)
-    if runtime == "codex":
-        return {
-            "name": "codex",
-            "dispatchMode": "render-only",
-            "sessionAccounting": "artifact-only",
-        }
-    return {
-        "name": "claude-code",
-        "dispatchMode": "team",
-        "sessionAccounting": "claude-jsonl",
-    }
+    return _lead_info(ctx).adapter_payload()
 
 
 _PHASE_BLOCK_RE = re.compile(
@@ -1734,6 +1728,16 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         f"--project-root {ctx.get('PROJECT_ROOT', '')} "
         f"--run-manifest {ctx.get('RUN_MANIFEST_RELATIVE_PATH', '')}"
     )
+    team_dispatch_command = (
+        "okstra team dispatch "
+        f"--project-root {ctx.get('PROJECT_ROOT', '')} "
+        f"--run-manifest {ctx.get('RUN_MANIFEST_RELATIVE_PATH', '')}"
+    )
+    team_await_command = (
+        "okstra team await "
+        f"--project-root {ctx.get('PROJECT_ROOT', '')} "
+        f"--run-manifest {ctx.get('RUN_MANIFEST_RELATIVE_PATH', '')}"
+    )
     if task_type == "release-handoff" or not selected:
         team_creation_gate_block = (
             "## Single-Lead Phase (no team creation)\n"
@@ -1773,6 +1777,27 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
             "worker prompt histories when missing, persists worker results, and\n"
             "runs post-report validation for the Codex report-writer path."
         )
+    elif lead_runtime == "external":
+        team_creation_gate_block = (
+            "## Tmux Worker Dispatch Gate (BLOCKING)\n"
+            "\n"
+            "This run was prepared for `leadRuntime=external`. Do NOT call "
+            "`TeamCreate`, do NOT call Claude Code `Agent(...)`, and do NOT call "
+            "`okstra codex-dispatch`. This adapter dispatches workers through "
+            "okstra-owned tmux panes.\n"
+            "\n"
+            "Required actions, in order:\n"
+            "1. Inspect the run manifest and team-state paths listed below.\n"
+            "2. Emit `PROGRESS: phase-3-team-create skipped (tmux-pane)`; there is no Claude Teams surface in this adapter.\n"
+            "3. Plan worker execution with:\n"
+            f"   `{team_dispatch_command} --dry-run`\n"
+            "4. Dispatch workers with:\n"
+            f"   `{team_dispatch_command}`\n"
+            "5. Arm one background wait using this harness's async shell primitive:\n"
+            f"   `{team_await_command}`\n"
+            "6. On wake, read team-state. Worker completion is valid only from "
+            "`workerDispatches[]` plus result files; pane creation alone is not completion."
+        )
     elif task_type == "implementation" and concurrent_stages:
         team_creation_gate_block = (
             "## Concurrent-run: no-team background (BLOCKING)\n"
@@ -1852,7 +1877,33 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
             "response is to go back to step 2 — NOT to strip `team_name` and retry."
         )
 
-    if lead_runtime == "codex":
+    if lead_runtime == "external":
+        lead_intro_line = f"You are `{lead_role}` for project `{ctx.get('PROJECT_ID', '')}`."
+        lead_bootstrap_instruction = (
+            "Read the manifests below for all task metadata, paths, model "
+            "assignments, and worker roster. Use the tmux worker dispatch gate "
+            "in this prompt; do not invoke Claude Code skills."
+        )
+        lead_session_block = (
+            "## Session\n"
+            "\n"
+            "- Lead runtime: `external`\n"
+            "- Lead session accounting: artifact-only; this harness does not expose Claude Code jsonl session IDs."
+        )
+        worker_dispatch_guidance = (
+            "## Tmux Worker Dispatch\n"
+            "\n"
+            "- Worker prompt paths in `task-manifest.json` are assigned history "
+            "locations. `okstra team dispatch` materializes missing prompt files "
+            "from the run manifest and active-run-context; existing prompt files "
+            "are never overwritten.\n"
+            "- Do not call `TeamCreate`, `Agent(...)`, or `okstra codex-dispatch`. "
+            "Use `okstra team dispatch` and `okstra team await` from the gate "
+            "above for worker execution.\n"
+            "- File presence is not a signal to skip. Worker selection and skipped "
+            "statuses come from `team-state`, never from the prompts directory."
+        )
+    elif lead_runtime == "codex":
         lead_intro_line = f"You are `{lead_role}` for project `{ctx.get('PROJECT_ID', '')}`."
         lead_bootstrap_instruction = (
             "Read the manifests below for all task metadata, paths, model "

package/runtime/python/okstra_ctl/run.py

@@ -40,6 +40,7 @@ from .material import (
 )
 from .final_report_schema import load_schema
 from .lead_events import LeadEvent, append_lead_event
+from .lead_runtime import ALLOWED_LEAD_RUNTIMES
 from .models import ModelAssignment, resolve_model_metadata
 from .schema_excerpt import build_schema_excerpt
 from .path_resolve import relative_to_project_root, resolve_user_file
@@ -81,7 +82,7 @@ from .workers import (
     resolve_profile_workers,
     validate_workers_against_profile,
 )
-from .workflow import compute_workflow_state
+from .workflow import compute_workflow_state, load_phase_forbidden
 from .locks import worktree_provision_mutex
 from .worktree import (
     WorktreeProvision,
@@ -267,7 +268,7 @@ class PrepareError(Exception):
     """surface to caller — task bundle prepare failed."""
 
 
-_ALLOWED_LEAD_RUNTIMES = ("claude-code", "codex")
+_ALLOWED_LEAD_RUNTIMES = ALLOWED_LEAD_RUNTIMES
 
 
 def _normalize_lead_runtime(value: str) -> str:
@@ -945,14 +946,14 @@ def _brief_sha256(path: Path) -> str:
         return ""
 
 
-def _record_codex_render_only_event(inp: PrepareInputs, ctx: dict) -> None:
-    if inp.lead_runtime != "codex" or not inp.render_only:
+def _record_artifact_runtime_render_only_event(inp: PrepareInputs, ctx: dict) -> None:
+    if inp.lead_runtime not in ("codex", "external") or not inp.render_only:
         return
     append_lead_event(
         Path(ctx["LEAD_EVENTS_PATH"]),
         LeadEvent(
             event_type="bundle-prepared",
-            lead_runtime="codex",
+            lead_runtime=inp.lead_runtime,
             task_key=ctx["TASK_KEY"],
             task_type=ctx["TASK_TYPE"],
             run_seq=ctx["RUN_MANIFESTS_SEQ"],
@@ -1807,6 +1808,7 @@ def _write_instruction_set_sources(
         "EXECUTOR_WORKTREE_BASE_REF",
         "EXECUTOR_WORKTREE_STATUS",
         "EXECUTOR_WORKTREE_NOTE",
+        "PHASE_FORBIDDEN_ACTIONS",
     ):
         profile_rendered = profile_rendered.replace("{{" + key + "}}", ctx.get(key, ""))
     (instruction_set / "analysis-profile.md").write_text(profile_rendered, encoding="utf-8")
@@ -1997,7 +1999,8 @@ def _record_fix_cycle_events(inp: PrepareInputs, ctx: dict) -> str:
 
 
 def _finalize_status_and_render_manifests(
-    inp: PrepareInputs, ctx: dict, task_index_template: Path
+    inp: PrepareInputs, ctx: dict, task_index_template: Path,
+    forbidden_by_phase: dict[str, str],
 ) -> None:
     """최종 task/run status 를 확정하고 workflow state 를 재계산한 뒤 team-state,
     task-manifest, task-index, run-manifest, timeline, discovery 산출물을 렌더한다."""
@@ -2014,6 +2017,7 @@ def _finalize_status_and_render_manifests(
         current_run_status=ctx["CURRENT_RUN_STATUS"],
         current_task_status=ctx["CURRENT_TASK_STATUS"],
         render_only=inp.render_only,
+        forbidden_by_phase=forbidden_by_phase,
         work_category=inp.work_category,
     ))
     render_team_state(ctx["TEAM_STATE_PATH"], ctx)
@@ -2054,7 +2058,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     if lead_runtime != "claude-code" and not inp.render_only:
         raise PrepareError(
             f"lead runtime `{lead_runtime}` is currently render-only; "
-            "use --render-only until the Codex dispatch adapter is implemented."
+            "use --render-only until a dispatch backend is enabled for this lead runtime."
         )
 
     # ---- input validation + asset resolution + roster/model 해소 ----
@@ -2229,11 +2233,13 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     # ---- initial workflow state (current_run_status not yet known) ----
     initial_task_status = "ready-for-claude"
     initial_run_status = "not-run"
+    forbidden_by_phase = load_phase_forbidden(workspace_root)
     workflow_state = compute_workflow_state(
         task_type=inp.task_type,
         current_run_status=initial_run_status,
         current_task_status=initial_task_status,
         render_only=inp.render_only,
+        forbidden_by_phase=forbidden_by_phase,
     )
 
     # ---- assemble full ctx (the values render functions expect) ----
@@ -2329,8 +2335,10 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     _persist_run_inputs(inp, ctx, models, selected_reviewers, brief_relative)
 
     # ---- final status + manifest/discovery renders ----
-    _finalize_status_and_render_manifests(inp, ctx, task_index_template)
-    _record_codex_render_only_event(inp, ctx)
+    _finalize_status_and_render_manifests(
+        inp, ctx, task_index_template, forbidden_by_phase
+    )
+    _record_artifact_runtime_render_only_event(inp, ctx)
 
     # ---- central index ----
     initial_status = "prepared" if inp.render_only else "running"
@@ -2411,9 +2419,9 @@ def main(argv: list[str]) -> int:
         choices=list(_ALLOWED_LEAD_RUNTIMES),
         dest="lead_runtime",
         help=(
-            "Lead runtime adapter. Default: claude-code. `codex` is accepted "
-            "for render-only artifact preparation while the dispatch adapter "
-            "is implemented."
+            "Lead runtime adapter. Default: claude-code. `codex` renders "
+            "Codex CLI artifact bundles; `external` renders neutral bootstrap "
+            "bundles for manifest inspection until a dispatch backend is enabled."
         ),
     )
     p.add_argument("--executor", default="")