okstra 0.1.0

package/runtime/python/okstra_ctl/run_context.py

@@ -0,0 +1,166 @@
+"""run-scoped state 의 file-based 저장/조회.
+
+설계 원칙:
+  - 한 run 의 입력 (`task-type`, `brief-path`, `directive`, `workers`, `models`,
+    `related-tasks`, `approved-plan`, `clarification-response`) 은
+    `<run-dir>/manifests/run-inputs-<seq>.json` 에 박힌다.
+  - 한 run 의 계산된 paths/seqs/timestamp 는
+    `<run-dir>/manifests/run-context-<seq>.json` 에 박힌다.
+  - 두 파일이 한 번 디스크에 자리잡으면, 이후 모든 reader 는 환경 변수에 의존
+    하지 않고 같은 값을 돌려준다 → 같은 claude 세션의 두 병렬 호출이 stale
+    snapshot 을 보지 않는다.
+
+부수효과 함수는 모두 per-task 락 (`~/.okstra/.locks/<task-key>.lock`) 안에서만
+seq advance 와 파일 쓰기를 수행한다.
+"""
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterator, Optional
+
+from .paths import compute_run_paths
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _okstra_home() -> Path:
+    home = os.environ.get("OKSTRA_HOME")
+    if home:
+        return Path(home)
+    return Path.home() / ".okstra"
+
+
+def _task_lock_path(task_key: str) -> Path:
+    """task-key 별 mutex 파일. central index 와는 별개로 task 단위 직렬화."""
+    home = _okstra_home()
+    locks = home / ".locks"
+    locks.mkdir(parents=True, exist_ok=True)
+    safe = task_key.replace("/", "_").replace(":", "_")
+    return locks / f"{safe}.lock"
+
+
+@contextmanager
+def task_mutex(task_key: str) -> Iterator[None]:
+    """task-key per-process mutex. 동시 호출은 락 안에서 직렬화된다."""
+    path = _task_lock_path(task_key)
+    path.touch(exist_ok=True)
+    with path.open("r+") as f:
+        fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+
+
+def _atomic_write_json(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n",
+                   encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def _run_context_filename(task_type_segment: str, seq: str) -> str:
+    return f"run-context-{task_type_segment}-{seq}.json"
+
+
+def _run_inputs_filename(task_type_segment: str, seq: str) -> str:
+    return f"run-inputs-{task_type_segment}-{seq}.json"
+
+
+def compute_and_write_run_context(
+    *,
+    workspace_root: Path,
+    project_root: Path,
+    project_id: str,
+    task_group: str,
+    task_id: str,
+    task_type: str,
+    run_seq_override: Optional[int] = None,
+) -> dict:
+    """task per-mutex 안에서 run paths 를 계산하고 디스크에 박는다.
+
+    기존 next_run_seq 가 디스크 스캔 기반이라 두 호출이 동시에 진행되면 같은
+    seq 를 받을 수 있다. mutex 안에서 (a) seq 계산 (b) run-context.json 저장
+    이 한 트랜잭션으로 묶이면, 다음 호출은 새로 박힌 파일을 보고 다음 seq 를
+    돌려준다. 락은 OKSTRA_HOME/.locks/<task-key>.lock.
+
+    반환값: paths dict + 부가 메타(`runTimestamp`, 저장된 파일 경로 등).
+    """
+    project_root = Path(project_root)
+    workspace_root = Path(workspace_root)
+    task_key = f"{project_id}:{task_group}:{task_id}"
+
+    with task_mutex(task_key):
+        ctx = compute_run_paths(
+            project_root=project_root,
+            workspace_root=workspace_root,
+            project_id=project_id,
+            task_group=task_group,
+            task_id=task_id,
+            task_type=task_type,
+            run_seq_override=run_seq_override,
+        )
+        ctx["RUN_TIMESTAMP_ISO"] = _now_iso()
+        run_manifests_dir = Path(ctx["RUN_MANIFESTS_DIR"])
+        ctx_path = run_manifests_dir / _run_context_filename(
+            ctx["TASK_TYPE_SEGMENT"], ctx["RUN_MANIFESTS_SEQ"])
+        ctx["RUN_CONTEXT_FILE"] = str(ctx_path)
+        ctx["RUN_CONTEXT_RELATIVE_PATH"] = (
+            str(ctx_path.relative_to(project_root.resolve()))
+            if ctx_path.resolve().is_relative_to(project_root.resolve())
+            else str(ctx_path))
+        _atomic_write_json(ctx_path, ctx)
+    return ctx
+
+
+def write_run_inputs(
+    *,
+    project_root: Path,
+    run_manifests_dir: Path,
+    task_type_segment: str,
+    seq: str,
+    inputs: dict,
+) -> Path:
+    """사용자 입력(brief, directive, workers, models, ...) 을 run-inputs 파일에
+    박는다. 호출자가 미리 계산한 seq 를 그대로 사용한다(같은 트랜잭션 내).
+
+    inputs schema (모든 키 optional):
+      taskBriefPath, directive, workers, leadModel, claudeModel, codexModel,
+      geminiModel, reportWriterModel, relatedTasks, approvedPlanPath,
+      clarificationResponsePath, renderOnly, refreshAssets
+    """
+    run_manifests_dir = Path(run_manifests_dir)
+    path = run_manifests_dir / _run_inputs_filename(task_type_segment, seq)
+    payload = {
+        "schemaVersion": "1.0",
+        "writtenAt": _now_iso(),
+        "inputs": dict(inputs),
+    }
+    _atomic_write_json(path, payload)
+    return path
+
+
+def read_run_context(run_manifests_dir: Path, task_type_segment: str,
+                     seq: str) -> Optional[dict]:
+    """run-context-<task-type>-<seq>.json 을 dict 로 돌려준다. 부재 시 None."""
+    path = Path(run_manifests_dir) / _run_context_filename(task_type_segment, seq)
+    if not path.is_file():
+        return None
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def read_run_inputs(run_manifests_dir: Path, task_type_segment: str,
+                    seq: str) -> Optional[dict]:
+    """run-inputs-<task-type>-<seq>.json 을 dict 로. 부재 시 None."""
+    path = Path(run_manifests_dir) / _run_inputs_filename(task_type_segment, seq)
+    if not path.is_file():
+        return None
+    return json.loads(path.read_text(encoding="utf-8"))

package/runtime/python/okstra_ctl/seeding.py

@@ -0,0 +1,97 @@
+"""okstra runtime asset verification + per-run runtime settings.
+
+okstra 가 깔아둔 런타임(`~/.okstra/lib/python`, `~/.okstra/bin`,
+`~/.okstra/version`) 이 있는지 확인하고, 누락 시 InstallationError 로
+surface 한다. 또한 claude 런치 때 사용할 휘발성 settings 파일을 현재 run
+디렉토리에 만든다.
+"""
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Optional
+
+
+class InstallationError(Exception):
+    """okstra 가 깔아둔 런타임 자산이 누락됨."""
+
+
+def required_install_paths() -> list[Path]:
+    """okstra install 이 채워야 하는 최소 자산 경로."""
+    okstra_home = Path.home() / ".okstra"
+    return [
+        okstra_home / "lib" / "python" / "okstra_project",
+        okstra_home / "lib" / "python" / "okstra_ctl",
+        okstra_home / "bin" / "okstra.sh",
+        okstra_home / "version",
+    ]
+
+
+def verify_installation(workspace_root: Path) -> None:
+    """누락된 자산이 있으면 `InstallationError` 를 raise. 메시지에 install
+    명령을 포함한다.
+
+    workspace_root 는 prompts/, templates/, validators/, agents/ 를 담은
+    디렉터리(`<okstra-package>/runtime` 또는 dev-link 모드의 repo 루트)다.
+    이 검사는 ~/.okstra 자산만을 본다; workspace_root 의 존재는 별도 검증.
+    """
+    missing = [p for p in required_install_paths() if not p.exists()]
+    if missing:
+        msg_lines = [f"okstra runtime missing: {p}" for p in missing]
+        msg_lines.append("")
+        msg_lines.append("okstra has not been installed yet. Run once:")
+        msg_lines.append("  npx okstra@latest install")
+        raise InstallationError("\n".join(msg_lines))
+
+    workspace_root = Path(workspace_root)
+    if not workspace_root.is_dir():
+        raise InstallationError(
+            f"okstra workspace not found: {workspace_root}\n"
+            "Ensure 'okstra paths --field workspace' resolves to an existing directory."
+        )
+
+
+def cleanup_obsolete_generated_docs(
+    *, project_root: Path, instruction_set_dir: Path,
+) -> None:
+    """과거 위치에 남아 있을 수 있는 deprecated 문서들을 best-effort 삭제."""
+    project_root = Path(project_root)
+    legacy_root = project_root / ".project-docs" / "ai"
+    for rel in (
+        "claude-skill-index.md",
+        "okstra/okstra-guide.md",
+        "okstra/worker-catalog.md",
+    ):
+        target = legacy_root / rel
+        if target.exists():
+            try:
+                target.unlink()
+            except OSError:
+                pass
+    obsolete = Path(instruction_set_dir) / "okstra-skill.md"
+    if obsolete.exists():
+        try:
+            obsolete.unlink()
+        except OSError:
+            pass
+    okstra_dir = legacy_root / "okstra"
+    if okstra_dir.is_dir():
+        try:
+            okstra_dir.rmdir()
+        except OSError:
+            pass
+
+
+def render_runtime_settings_file(
+    *, workspace_root: Path, run_dir: Path,
+) -> Optional[Path]:
+    """`templates/reports/settings.template.json` 을 `<run-dir>/okstra-runtime-settings.json`
+    으로 복사한다. 템플릿 부재 시 None 반환(상위에서 `--settings` 인자 skip).
+    """
+    template = Path(workspace_root) / "templates" / "reports" / "settings.template.json"
+    if not template.is_file():
+        return None
+    target = Path(run_dir) / "okstra-runtime-settings.json"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(template, target)
+    return target

package/runtime/python/okstra_ctl/sequence.py

@@ -0,0 +1,53 @@
+"""run_seq 예측."""
+from __future__ import annotations
+
+import re as _re
+from pathlib import Path
+from typing import Optional
+
+from .ids import slugify_task_segment
+from .jsonl import read_jsonl
+
+
+def predict_next_run_seq(project_root: Path, task_group: str, task_id: str,
+                         task_type: str, *,
+                         home: Optional[Path] = None,
+                         project_id: Optional[str] = None) -> int:
+    """타깃 프로젝트와 (선택적) 중앙 인덱스를 합쳐 다음 run_seq 를 계산.
+
+    스캔 소스:
+      1. reports/ 의 final-report-<task_type>-<seq:03d>.md (완료된 run)
+      2. manifests/ 의 run-manifest-<task_type>-<seq:03d>.json (시작했지만 종료 전)
+      3. home/active.jsonl 의 같은 (project_id, group, task_id, task_type) row
+         (다른 okstra-ctl 프로세스가 이미 예약한 in-flight run) — home/project_id 가 주어진 경우만
+
+    이 셋의 max + 1 이 안전한 다음 seq.
+    """
+    task_type_segment = slugify_task_segment(task_type)
+    base = (project_root / ".project-docs" / "okstra" / "tasks"
+            / slugify_task_segment(task_group) / slugify_task_segment(task_id)
+            / "runs" / task_type_segment)
+    max_seq = 0
+    rep_pat = _re.compile(rf"^final-report-{_re.escape(task_type_segment)}-(\d+)\.md$")
+    man_pat = _re.compile(rf"^run-manifest-{_re.escape(task_type_segment)}-(\d+)\.json$")
+    for sub, pat in (("reports", rep_pat), ("manifests", man_pat)):
+        d = base / sub
+        if not d.is_dir():
+            continue
+        for child in d.iterdir():
+            m = pat.match(child.name)
+            if m:
+                n = int(m.group(1))
+                if n > max_seq:
+                    max_seq = n
+    if home is not None and project_id is not None:
+        for src in ("active.jsonl", "recent.jsonl"):
+            for r in read_jsonl(home / src):
+                if (r.get("projectId") == project_id
+                        and r.get("taskGroup") == task_group
+                        and r.get("taskId") == task_id
+                        and r.get("taskType") == task_type):
+                    s = int(r.get("runSeq", 0))
+                    if s > max_seq:
+                        max_seq = s
+    return max_seq + 1

package/runtime/python/okstra_ctl/session.py

@@ -0,0 +1,33 @@
+"""Claude session helpers.
+
+bash session.sh 의 python 구현. claude session id 생성, resume command
+파일 작성.
+"""
+from __future__ import annotations
+
+import os
+import uuid
+from pathlib import Path
+
+
+def generate_claude_session_id() -> str:
+    """UUIDv4 문자열."""
+    return str(uuid.uuid4())
+
+
+def write_claude_resume_command_file(
+    *, resume_command_path: Path, project_root: Path, claude_session_id: str,
+) -> None:
+    """`bash claude-resume-*.sh` 를 실행하면 task 의 claude 세션을 resume
+    하도록 shell 스크립트를 작성하고 chmod +x.
+    """
+    resume_command_path = Path(resume_command_path)
+    resume_command_path.parent.mkdir(parents=True, exist_ok=True)
+    body = (
+        "#!/usr/bin/env bash\n"
+        "# Generated by okstra. Resume the prepared Claude session for this run.\n"
+        f'cd "{project_root}"\n'
+        f'exec claude --resume "{claude_session_id}"\n'
+    )
+    resume_command_path.write_text(body, encoding="utf-8")
+    os.chmod(resume_command_path, 0o755)

package/runtime/python/okstra_ctl/tmux.py

@@ -0,0 +1,27 @@
+"""tmux 명령 빌더."""
+from __future__ import annotations
+
+from typing import Optional
+
+
+def _shell_quote(s: str) -> str:
+    """POSIX shell 안전 인용. shlex.quote 가 모든 메타문자(&, ;, |, *, ?, …) 를 처리한다."""
+    import shlex as _shlex
+    return _shlex.quote(s)
+
+
+def build_tmux_command(*, session_name: str, cwd: str, run_seq: int,
+                       argv: list, okstra_script: str,
+                       extra_env: Optional[dict] = None) -> list:
+    """tmux new-session 명령을 list 형태로 반환.
+    extra_env 의 키는 inner 명령 앞에 KEY=VAL 형태로 prepend 된다 — tmux 세션은
+    호출 셸의 환경을 자동 상속하지 않으므로 OKSTRA_HOME 등은 명시 전달해야 한다.
+    """
+    env_prefix = f"OKSTRA_RUN_SEQ_OVERRIDE={run_seq}"
+    if extra_env:
+        for k, v in extra_env.items():
+            env_prefix += f" {k}={_shell_quote(str(v))}"
+    # 스크립트 경로에 공백/메타문자가 있어도 안전하도록 동일 방식으로 인용.
+    inner = (f"{env_prefix} {_shell_quote(okstra_script)} "
+             + " ".join(_shell_quote(a) for a in argv))
+    return ["tmux", "new-session", "-d", "-s", session_name, "-c", cwd, inner]

package/runtime/python/okstra_ctl/workers.py

@@ -0,0 +1,64 @@
+"""Worker roster resolution.
+
+Profile 파일에서 권장 worker 목록을 뽑고(`resolve_profile_workers`), 사용자
+오버라이드와 합쳐 정규화한다(`normalize_workers`). bash workers.sh 의
+동등한 python 구현.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+ALLOWED_WORKERS = ["claude", "codex", "gemini", "report-writer"]
+PROFILE_BULLET_HEADERS = {"- Workers:", "- Reviewers:", "- Analysers:"}
+
+
+class WorkersError(Exception):
+    """invalid worker selection — surface to user."""
+
+
+def resolve_profile_workers(profile_path: Path) -> list[str]:
+    """`prompts/profiles/<task-type>.md` 본문의 `- Workers:` 섹션 아래
+    sub-bullet 들을 worker id 리스트로 돌려준다.
+    profile 파일이 없거나 섹션이 없으면 빈 리스트.
+    """
+    if not Path(profile_path).is_file():
+        return []
+    capturing = False
+    out: list[str] = []
+    for line in Path(profile_path).read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if stripped in PROFILE_BULLET_HEADERS:
+            capturing = True
+            continue
+        if not capturing:
+            continue
+        if line.startswith("- "):
+            break
+        if line.startswith("  - "):
+            out.append(line[4:].strip())
+            continue
+        if stripped:
+            break
+    return out
+
+
+def normalize_workers(value: str) -> list[str]:
+    """CSV 입력을 정규화한다.
+
+    - 공백 strip, 소문자화, 중복 제거(첫 출현 우선).
+    - 빈 입력이면 `ALLOWED_WORKERS` 전체를 default 로 사용.
+    - 허용 외 worker 가 포함되면 `WorkersError`.
+    """
+    items = [v.strip().lower() for v in (value or "").split(",") if v.strip()]
+    source = items or ALLOWED_WORKERS
+    unknown = [v for v in source if v not in ALLOWED_WORKERS]
+    if unknown:
+        raise WorkersError(f"unknown workers: {','.join(unknown)}")
+    seen: set[str] = set()
+    out: list[str] = []
+    for v in source:
+        if v in seen:
+            continue
+        seen.add(v)
+        out.append(v)
+    return out

package/runtime/python/okstra_ctl/workflow.py

@@ -0,0 +1,182 @@
+"""Phase / workflow state computation.
+
+bash `compute_workflow_render_context` + `default_next_phase_for_task_type` 의
+python 구현. (task-type, current task/run status, render-only flag) 만 받아서
+WORKFLOW_* 필드 dict 를 돌려준다.
+
+또한 task-type 별 PHASE_ALLOWED_OUTPUTS / PHASE_FORBIDDEN_ACTIONS 본문 매핑을
+모듈 상수로 보유.
+"""
+from __future__ import annotations
+
+PHASE_SEQUENCE = [
+    "requirements-discovery",
+    "error-analysis",
+    "implementation-planning",
+    "implementation",
+    "final-verification",
+]
+
+DEFAULT_NEXT_PHASE = {
+    "requirements-discovery": "pending-routing-decision",
+    "error-analysis": "implementation-planning",
+    "implementation-planning": "implementation",
+    "implementation": "final-verification",
+    "final-verification": "done-or-follow-up",
+}
+
+# Phase 별 allowed outputs / forbidden actions. bash heredoc 원문 그대로 옮긴 값.
+# 들여쓰기와 백틱은 prompt template 에 그대로 박혀 lead 가 읽는다.
+PHASE_RULES: dict[str, dict[str, str]] = {
+    "requirements-discovery": {
+        "allowed": (
+            "  - work-category classification (bugfix / feature / refactor / ops / improvement)\n"
+            "  - routing decision toward the next safe lifecycle phase\n"
+            "  - missing-input list and clarification requests\n"
+            "  - approval / confirmation checkpoints recorded for the next phase"
+        ),
+        "forbidden": (
+            "  - source code edits of any kind\n"
+            "  - implementation planning or detailed design beyond what is required to choose the next phase\n"
+            "  - executing builds, migrations, deployments, or any state-mutating command\n"
+            "  - starting `error-analysis`, `implementation-planning`, or `implementation` inside this run (each must be a separate run, and `implementation` additionally requires an approved `implementation-planning` deliverable)"
+        ),
+    },
+    "error-analysis": {
+        "allowed": (
+            "  - symptom and trigger evidence\n"
+            "  - root-cause hypotheses with supporting citations\n"
+            "  - reproduction gaps and missing observability\n"
+            "  - validation paths to confirm or refute hypotheses"
+        ),
+        "forbidden": (
+            "  - source code edits, refactors, or fix attempts\n"
+            "  - implementation design or planning artifacts\n"
+            "  - executing builds, migrations, deployments, or any state-mutating command\n"
+            "  - starting `implementation-planning` or `implementation` inside this run (each must be a separate run, and `implementation` additionally requires an approved `implementation-planning` deliverable)"
+        ),
+    },
+    "implementation-planning": {
+        "allowed": (
+            "  - pre-planning context exploration notes (files/interfaces inspected, recent commits scanned, ambiguities flagged)\n"
+            "  - at least two implementation option candidates, each with a File Structure list (Create/Modify/Delete with one-line responsibility per file), affected interfaces, and blast-radius estimate\n"
+            "  - trade-off matrix across options (complexity, risk, reversibility, test cost, rollout cost) and recommended option with rationale tied to isolation / single-responsibility / YAGNI principles\n"
+            "  - bite-sized stepwise execution order for the recommended option (each step ~2-5 min, exact file paths and commands, TDD ordering when applicable, no placeholders)\n"
+            "  - dependency / migration risk assessment, validation checklist (pre / mid / post with exact commands), rollback strategy with revert path and trigger signal\n"
+            "  - `Open Questions` block listing every unresolved ambiguity\n"
+            "  - explicit `User Approval Request` block awaiting human approval\n"
+            "  - self-review confirmation (spec coverage, placeholder scan, internal consistency, ambiguity, scope)"
+        ),
+        "forbidden": (
+            "  - source code edits of any kind (Edit/Write on project source files is forbidden)\n"
+            "  - file writes outside the run`s artifact directories (`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`); in particular, do not write to `docs/superpowers/specs/` or `docs/superpowers/plans/`\n"
+            "  - executing builds, migrations, deployments, or any state-mutating command\n"
+            '  - starting `implementation` inside this run (must be a separate run authorised by an approved deliverable from this phase), even if the user says "다음 단계 진행해"\n'
+            "  - dispatching parallel sub-agents beyond the required worker roster (okstra owns worker fan-out)\n"
+            '  - leaving placeholders such as TBD / TODO / "handle edge cases" / "similar to Option N" in the report\n'
+            "  - delegating the self-review pass to a generic subagent — `Claude lead` must run it"
+        ),
+    },
+    "implementation": {
+        "allowed": (
+            "  - approved-plan reference and quoted user-approval evidence\n"
+            "  - commit list with SHA, message, and the plan step each commit satisfies\n"
+            "  - `git diff --stat <base>..HEAD` summary plus per-file one-line change summary\n"
+            "  - `Out-of-plan edits` block listing every file touched outside the approved plan with rationale (empty block preferred)\n"
+            '  - validation evidence: actual stdout/stderr and exit code for every pre / mid / post command from the plan (no paraphrased "tests pass")\n'
+            "  - TDD evidence for TDD-applicable steps: failing-test output before implementation commit and passing-test output after, with framing SHAs\n"
+            "  - per-verifier sections (`Gemini verifier`, `Codex verifier`, `Claude verifier`) with independent verdict (PASS / CONCERNS / FAIL) and cited diff snippets; dissent is preserved by `Claude lead`\n"
+            "  - rollback verification (revert SHA reachable, feature flag toggle works, migration down step valid; dry-run preferred)\n"
+            "  - routing recommendation for `final-verification` (ready / needs new error-analysis or planning loop)"
+        ),
+        "forbidden": (
+            "  - any Edit/Write or state-mutating Bash before the pre-implementation gate passes (gate requires --approved-plan pointing to a final-report.md with a recorded user approval marker)\n"
+            "  - `git push` of any kind, `npm publish` / `cargo publish` / `pip publish`, `gh release`, `docker push`\n"
+            "  - real database migrations, schema changes against shared environments, or writes to non-local datastores\n"
+            "  - production credentials, deploy commands, infra mutation (`terraform apply`, `kubectl apply` against non-local cluster, etc.)\n"
+            "  - external API write calls (POST/PUT/PATCH/DELETE) to third-party services other than localhost test fixtures\n"
+            "  - source edits or Bash mutations performed by any verifier role (`Gemini verifier`, `Codex verifier`, `Claude verifier` are read-only — recommend, do not apply)\n"
+            "  - dispatching parallel sub-agents beyond the required worker roster\n"
+            "  - silent scope expansion: every file edited outside the approved plan list MUST appear in the `Out-of-plan edits` block with rationale\n"
+            '  - leaving placeholders such as TBD / TODO / "implement later" / "handle edge cases" in committed code\n'
+            '  - declaring overall task acceptance — that is `final-verification` ownership; this phase reports only "ready for final-verification" or "needs new planning loop"\n'
+            "  - delegating the self-review pass to a generic subagent — `Claude lead` must run it"
+        ),
+    },
+    "final-verification": {
+        "allowed": (
+            "  - acceptance verdict with requirement coverage assessment\n"
+            "  - residual risk and regression notes\n"
+            "  - recommended follow-up routing (`error-analysis` / `implementation-planning`) for any defects detected"
+        ),
+        "forbidden": (
+            "  - source code edits, follow-up bug fixes, or scope expansion\n"
+            "  - state-mutating commands; only read-only execution of pre-existing test or validation commands is permitted\n"
+            "  - starting any follow-up phase inside this run; record findings and end the run"
+        ),
+    },
+}
+
+PHASE_RULES_UNKNOWN = {
+    "allowed": "  - outputs defined by the active task type",
+    "forbidden": (
+        "  - any action that belongs to a different lifecycle phase\n"
+        "  - source code edits or state-mutating commands unless this task type explicitly authorises them"
+    ),
+}
+
+
+def default_next_phase_for(task_type: str) -> str:
+    return DEFAULT_NEXT_PHASE.get(task_type, "unknown")
+
+
+def compute_workflow_state(
+    *,
+    task_type: str,
+    current_run_status: str,
+    current_task_status: str,
+    render_only: bool,
+) -> dict:
+    """WORKFLOW_* + PHASE_* 값을 dict 로 돌려준다."""
+    if current_run_status == "in-progress":
+        phase_state = "in-progress"
+    elif current_run_status == "prepared":
+        phase_state = "prepared"
+    elif current_run_status in ("error", "timeout", "contract-violated"):
+        phase_state = "blocked"
+    elif current_run_status == "completed":
+        phase_state = "completed"
+    else:
+        if current_task_status in (
+            "instruction-set-generated",
+            "ready-for-claude",
+            "claude-session-started",
+        ):
+            phase_state = "prepared"
+        else:
+            phase_state = "not-started"
+
+    routing_status = "pending" if task_type == "requirements-discovery" else "not-applicable"
+
+    if render_only:
+        checkpoint_label = "instruction-set-prepared"
+    elif current_run_status == "in-progress":
+        checkpoint_label = "interactive-session-handoff"
+    else:
+        checkpoint_label = "run-prepared"
+
+    rules = PHASE_RULES.get(task_type, PHASE_RULES_UNKNOWN)
+    last_completed = task_type if current_run_status == "completed" else ""
+
+    return {
+        "WORKFLOW_WORK_CATEGORY": "unknown",
+        "WORKFLOW_CURRENT_PHASE": task_type,
+        "WORKFLOW_CURRENT_PHASE_STATE": phase_state,
+        "WORKFLOW_NEXT_RECOMMENDED_PHASE": default_next_phase_for(task_type),
+        "WORKFLOW_LAST_COMPLETED_PHASE": last_completed,
+        "WORKFLOW_AWAITING_APPROVAL": "false",
+        "WORKFLOW_ROUTING_STATUS": routing_status,
+        "WORKFLOW_LAST_SAFE_CHECKPOINT_LABEL": checkpoint_label,
+        "PHASE_ALLOWED_OUTPUTS": rules["allowed"],
+        "PHASE_FORBIDDEN_ACTIONS": rules["forbidden"],
+    }

package/runtime/python/okstra_project/__init__.py

@@ -0,0 +1,41 @@
+"""Project root self-registration model.
+
+`<PROJECT_ROOT>/.project-docs/okstra/project.json` 을 권위 소스로 삼아
+PROJECT_ROOT 를 해석하고, 실행 시점에 upsert 한다. 과거 모델
+(`examples/projects/<id>.conf.sh`) 는 폐기되었다.
+"""
+from __future__ import annotations
+
+from .resolver import (
+    ResolverError,
+    project_json_path,
+    resolve_project_root,
+    upsert_project_json,
+)
+from .state import (
+    StateError,
+    find_task_root,
+    list_project_tasks,
+    parse_task_key,
+    read_latest_task,
+    read_task_catalog,
+    read_task_manifest,
+    resolve_task_identity,
+    slugify,
+)
+
+__all__ = [
+    "ResolverError",
+    "StateError",
+    "project_json_path",
+    "resolve_project_root",
+    "upsert_project_json",
+    "find_task_root",
+    "list_project_tasks",
+    "parse_task_key",
+    "read_latest_task",
+    "read_task_catalog",
+    "read_task_manifest",
+    "resolve_task_identity",
+    "slugify",
+]