okstra 0.76.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_events.py

@@ -0,0 +1,129 @@
+"""Structured JSONL events emitted by non-Claude lead runtimes."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Mapping
+
+
+REQUIRED_FIELDS = (
+    "eventType",
+    "leadRuntime",
+    "taskKey",
+    "taskType",
+    "runSeq",
+    "timestamp",
+    "details",
+)
+
+
+class LeadEventParseError(ValueError):
+    """Raised when a lead-events JSONL file contains an invalid row."""
+
+    def __init__(self, path: Path, line_number: int, message: str) -> None:
+        super().__init__(f"{path}:{line_number}: {message}")
+        self.path = path
+        self.line_number = line_number
+
+
+@dataclass(frozen=True)
+class LeadEvent:
+    event_type: str
+    lead_runtime: str
+    task_key: str
+    task_type: str
+    run_seq: str
+    timestamp: str
+    details: Mapping[str, Any] = field(default_factory=dict)
+
+    def to_record(self) -> dict[str, Any]:
+        return {
+            "eventType": self.event_type,
+            "leadRuntime": self.lead_runtime,
+            "taskKey": self.task_key,
+            "taskType": self.task_type,
+            "runSeq": self.run_seq,
+            "timestamp": self.timestamp,
+            "details": _stable_json_value(dict(self.details)),
+        }
+
+    @classmethod
+    def from_record(cls, record: Mapping[str, Any]) -> "LeadEvent":
+        missing = [field_name for field_name in REQUIRED_FIELDS
+                   if field_name not in record]
+        if missing:
+            raise ValueError(
+                "missing required lead event field(s): " + ", ".join(missing)
+            )
+        details = record["details"]
+        if not isinstance(details, Mapping):
+            raise ValueError("lead event details must be a JSON object")
+        return cls(
+            event_type=_require_string(record, "eventType"),
+            lead_runtime=_require_string(record, "leadRuntime"),
+            task_key=_require_string(record, "taskKey"),
+            task_type=_require_string(record, "taskType"),
+            run_seq=_require_string(record, "runSeq"),
+            timestamp=_require_string(record, "timestamp"),
+            details=dict(details),
+        )
+
+
+def append_lead_event(path: Path, event: LeadEvent) -> None:
+    """Append one lead event as compact JSONL, creating parent directories."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as f:
+        f.write(_event_json(event) + "\n")
+
+
+def read_lead_events(path: Path) -> list[LeadEvent]:
+    """Parse a lead-events JSONL file.
+
+    Missing files read as an empty log. Blank lines are ignored. Malformed JSON
+    and malformed event objects fail loudly with path and line number context.
+    """
+    if not path.is_file():
+        return []
+    events: list[LeadEvent] = []
+    for line_number, line in enumerate(
+        path.read_text(encoding="utf-8").splitlines(), start=1
+    ):
+        stripped = line.strip()
+        if not stripped:
+            continue
+        try:
+            record = json.loads(stripped)
+        except json.JSONDecodeError as exc:
+            raise LeadEventParseError(path, line_number, "invalid JSON") from exc
+        if not isinstance(record, Mapping):
+            raise LeadEventParseError(
+                path, line_number, "lead event row must be a JSON object"
+            )
+        try:
+            events.append(LeadEvent.from_record(record))
+        except ValueError as exc:
+            raise LeadEventParseError(path, line_number, str(exc)) from exc
+    return events
+
+
+def _event_json(event: LeadEvent) -> str:
+    return json.dumps(event.to_record(), ensure_ascii=False, separators=(",", ":"))
+
+
+def _require_string(record: Mapping[str, Any], field_name: str) -> str:
+    value = record[field_name]
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"lead event {field_name} must be a non-empty string")
+    return value
+
+
+def _stable_json_value(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {
+            key: _stable_json_value(value[key])
+            for key in sorted(value)
+        }
+    if isinstance(value, list):
+        return [_stable_json_value(item) for item in value]
+    return value

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/paths.py

@@ -175,6 +175,7 @@ def compute_run_paths(
     final_status = run_status / f"final{suffixes['status']}.status"
     team_state = run_state / f"team-state{suffixes['state']}.json"
     active_run_context = run_state / f"active-run-context{suffixes['state']}.json"
+    lead_events = run_state / f"lead-events-{task_type_segment}-{seqs['state']}.jsonl"
     final_report_template = instruction_set / "final-report-template.md"
     final_report_schema = instruction_set / "final-report-schema.json"
     reference_expectations = instruction_set / "reference-expectations.md"
@@ -241,6 +242,7 @@ def compute_run_paths(
         "FINAL_STATUS_PATH": str(final_status),
         "TEAM_STATE_PATH": str(team_state),
         "ACTIVE_RUN_CONTEXT_PATH": str(active_run_context),
+        "LEAD_EVENTS_PATH": str(lead_events),
         "FINAL_REPORT_TEMPLATE_PATH": str(final_report_template),
         "FINAL_REPORT_SCHEMA_PATH": str(final_report_schema),
         "REFERENCE_EXPECTATIONS_FILE": str(reference_expectations),
@@ -301,6 +303,7 @@ def compute_run_paths(
         ("FINAL_STATUS_RELATIVE_PATH", final_status),
         ("TEAM_STATE_RELATIVE_PATH", team_state),
         ("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", active_run_context),
+        ("LEAD_EVENTS_RELATIVE_PATH", lead_events),
         ("WORKER_RESULTS_RELATIVE_PATH", worker_results),
         ("RUN_CARRY_RELATIVE_PATH", run_carry),
         ("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", final_report_template),

package/runtime/python/okstra_ctl/pr_template.py

@@ -6,7 +6,7 @@ release-handoff 단계에서 lead 가 PR 본문을 작성할 때 사용하는
     1. per-run override (okstra-run Step 6 에서 입력)
     2. project: <project_root>/.okstra/project.json 의 ``prTemplatePath``
     3. global:  ~/.okstra/config.json 의 ``prTemplatePath``
-    4. default: 스킬 설치 디렉터리의 ``okstra-run/templates/pr-body.template.md``
+    4. default: 스킬 설치 디렉터리의 ``templates/prd/pr-body.template.md``
 
 경로는 절대경로 또는 ``~`` 시작 경로를 권장한다. 상대경로일 경우 project
 스코프는 ``project_root`` 기준, override 는 호출자 cwd 기준으로 해석한다.