okstra 0.12.0 → 0.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.12.0",
-  "builtAt": "2026-05-12T18:39:56.088Z",
+  "package": "0.13.1",
+  "builtAt": "2026-05-13T01:13:31.365Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/launch.template.md

@@ -22,6 +22,13 @@ Invoke the `okstra` skill now. Read the manifests below for all task metadata, p
 - All other paths in this prompt are relative to this root unless they begin with `/`.
 - When dispatching workers, you MUST include this absolute root in every worker prompt header so that workers do not depend on inherited cwd to resolve relative paths.
 
+## Worker Prompt Files (not pre-rendered)
+
+- The `runs/<phase>/prompts/<worker>-worker-prompt-*.md` files referenced in `task-manifest.json → artifacts.workerPromptPathByWorkerId` are **NOT** rendered by the okstra runtime. Those paths are the *assigned* locations where the prompt history MUST be written at dispatch time.
+- Therefore: at the start of every phase the prompts/ directory is normally empty (or contains only previously-dispatched workers' files). This is expected. Do NOT narrate it as "missing", "누락", or "not yet rendered" — it just means dispatch has not happened yet.
+- Before dispatching any required worker, **you (the lead) construct the worker prompt and persist it to the assigned absolute path using `Write`** (per `okstra-team-contract` rule 6). Only after persisting do you call the worker subagent (Agent tool / Codex / Gemini wrapper). The wrapper subagents will also re-write the same file on their end; the double-write is intentional and idempotent.
+- Do not "check if the file exists and skip dispatch" — file presence is not a signal to skip. Worker selection and skipping rules come from team-state, never from prompts/ directory contents.
+
 ## Manifests
 
 - Task manifest: `{{TASK_MANIFEST_RELATIVE_PATH}}`

package/runtime/python/okstra_ctl/worktree.py

@@ -32,6 +32,7 @@ Side effects:
 """
 from __future__ import annotations
 
+import json
 import os
 import subprocess
 from dataclasses import dataclass
@@ -54,13 +55,19 @@ OKSTRA_WORKTREES_RELATIVE = Path(".okstra/worktrees")
 # acceptable because okstra only writes inside its own task-scoped
 # subdirectory (e.g. `.project-docs/okstra/tasks/<task-id>/runs/...`).
 #
-# Override via the `OKSTRA_WORKTREE_SYNC_DIRS` env var: a colon-separated
-# list of project-root-relative paths that REPLACES this default. Use an
-# empty string to disable the feature entirely.
+# Override precedence (most-specific first):
+#   1. `OKSTRA_WORKTREE_SYNC_DIRS` env var — colon-separated list, REPLACES
+#      defaults. Empty string disables the feature entirely. One-off
+#      operator override.
+#   2. `worktreeSyncDirs` array in `.project-docs/okstra/project.json` —
+#      project-level config, persists across runs. Same semantics: array
+#      REPLACES defaults, empty array disables.
+#   3. The built-in `DEFAULT_WORKTREE_SYNC_DIRS` below.
 DEFAULT_WORKTREE_SYNC_DIRS: tuple[str, ...] = (
     ".project-docs",
     ".scratch",
     "graphify-out",
+    ".claude",
 )
 
 
@@ -172,18 +179,50 @@ def _main_worktree_path(project_root: Path) -> Path:
     return project_root
 
 
-def _resolve_sync_dirs() -> tuple[str, ...]:
+def _read_project_json_sync_dirs(project_root: Path) -> Optional[tuple[str, ...]]:
+    """Read `worktreeSyncDirs` from `.project-docs/okstra/project.json`.
+
+    Returns None if the field is absent or the file cannot be parsed (so
+    the caller falls back to defaults). Returns an empty tuple if the
+    field is explicitly an empty array (caller treats this as "disable").
+    A non-list value is treated as missing — we do not raise here because
+    sync-dir resolution must never block worktree provisioning.
+    """
+    target = project_root / ".project-docs" / "okstra" / "project.json"
+    if not target.is_file():
+        return None
+    try:
+        data = json.loads(target.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    value = data.get("worktreeSyncDirs")
+    if not isinstance(value, list):
+        return None
+    cleaned = tuple(
+        item.strip() for item in value
+        if isinstance(item, str) and item.strip()
+    )
+    return cleaned
+
+
+def _resolve_sync_dirs(project_root: Optional[Path] = None) -> tuple[str, ...]:
     """Return the list of project-root-relative dirs to symlink into the
-    new worktree. Reads `OKSTRA_WORKTREE_SYNC_DIRS` if set (colon-separated,
-    empty string disables); otherwise returns the built-in default.
+    new worktree. Precedence: env var → project.json → built-in default.
+    See the comment above `DEFAULT_WORKTREE_SYNC_DIRS` for full semantics.
     """
     raw = os.environ.get("OKSTRA_WORKTREE_SYNC_DIRS")
-    if raw is None:
-        return DEFAULT_WORKTREE_SYNC_DIRS
-    raw = raw.strip()
-    if not raw:
-        return ()
-    return tuple(part for part in (p.strip() for p in raw.split(":")) if part)
+    if raw is not None:
+        raw = raw.strip()
+        if not raw:
+            return ()
+        return tuple(part for part in (p.strip() for p in raw.split(":")) if part)
+    if project_root is not None:
+        from_project = _read_project_json_sync_dirs(project_root)
+        if from_project is not None:
+            return from_project
+    return DEFAULT_WORKTREE_SYNC_DIRS
 
 
 def _link_sync_dirs(source_root: Path, worktree_path: Path) -> list[str]:
@@ -201,7 +240,7 @@ def _link_sync_dirs(source_root: Path, worktree_path: Path) -> list[str]:
     caller can include them in the provisioning note.
     """
     notes: list[str] = []
-    for rel in _resolve_sync_dirs():
+    for rel in _resolve_sync_dirs(source_root):
         src = (source_root / rel).resolve()
         if not src.exists():
             continue

package/runtime/python/okstra_project/resolver.py

@@ -117,12 +117,15 @@ def upsert_project_json(project_root: Path, project_id: str, *,
                 f"or manually delete {target} if you intend to re-register this directory "
                 f"under a different id. "
                 f"(projectId 불일치: 한 PROJECT_ROOT 에는 하나의 projectId 만 허용됩니다.)")
-        result = {
-            "projectId": project_id,
-            "projectRoot": abs_root,
-            "createdAt": str(data.get("createdAt") or when),
-            "updatedAt": when,
-        }
+        # Preserve any user-managed fields (e.g. `worktreeSyncDirs`,
+        # `mcpServers`) so manual edits to project.json are not wiped
+        # by the per-run self-registration upsert. Only the canonical
+        # identity/timestamp fields below are owned by this function.
+        result = dict(data) if isinstance(data, dict) else {}
+        result["projectId"] = project_id
+        result["projectRoot"] = abs_root
+        result["createdAt"] = str(data.get("createdAt") or when)
+        result["updatedAt"] = when
     else:
         result = {
             "projectId": project_id,

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

@@ -148,15 +148,59 @@ If `implementation` chosen, ask two more `AskUserQuestion` in order:
 
 ## Step 6 (optional): Directive / workers / models / related / clarification
 
-Single `AskUserQuestion` first: `"Use default workers and models, or customize?"`
+Single `AskUserQuestion` first: `"기본 워커/모델로 진행할까요, 아니면 커스터마이즈할까요?"` (options: `Use defaults`, `Customize`).
 
 - `Use defaults` → all overrides remain empty.
-- `Customize` → ask each in turn (free text, blank = use default):
-  - workers CSV (subset of `claude,codex,gemini,report-writer`)
-  - `lead-model`, `claude-model`, `codex-model`, `gemini-model`, `report-writer-model`
-  - `directive`
-  - `related-tasks` CSV
-  - `clarification-response` path (relevant for follow-up `requirements-discovery` / `error-analysis` runs)
+- `Customize` → the prompts you ask depend on the `task_type` chosen in Step 4. Blank answer always means "use default". Never call the prompt label "worker CSV" — use plain Korean labels as shown below.
+
+### 6a. `implementation` phase (executor-driven)
+
+In this phase the roster is fixed by the profile (executor + two verifiers + report-writer). The Step 4 `executor` answer already determines who mutates code; verifier models use phase-specific defaults (`Claude verifier`=sonnet, `Codex verifier`=gpt-5.5, `Gemini verifier`=auto). So ask **only three model prompts**, plus directive/related/clarification:
+
+1. `"리더(Claude lead) 모델? (빈 칸 = 기본값)"` → `lead_model`
+2. `"실행자({executor-provider}) 모델? (빈 칸 = 기본값)"` → maps to `claude_model` / `codex_model` / `gemini_model` based on the Step 4 executor choice. The other two provider model fields stay empty (verifiers use defaults).
+3. `"리포트 작성자(report-writer) 모델? (빈 칸 = 기본값)"` → `report_writer_model`
+4. `"추가 directive (선택, 빈 칸 가능)"` → `directive`
+5. `"관련 task id 목록, 쉼표 구분 (선택, 빈 칸 가능)"` → `related_tasks_raw`
+
+Do NOT ask for `workers_override` in implementation — the profile's required roster must be preserved (verifier slots are mandatory). Leave `workers_override=""`.
+
+### 6b. Other phases (`requirements-discovery`, `error-analysis`, `implementation-planning`, `final-verification`, `release-handoff`)
+
+Ask each in turn (free text, blank = default):
+
+1. `"참여 워커 목록 (쉼표 구분, 빈 칸 = 프로필 기본값). 선택지: claude, codex, gemini, report-writer"` → `workers_override`
+2. `"리더(Claude lead) 모델? (빈 칸 = 기본값)"` → `lead_model`
+3. `"claude 워커 모델? (빈 칸 = 기본값)"` → `claude_model`
+4. `"codex 워커 모델? (빈 칸 = 기본값)"` → `codex_model`
+5. `"gemini 워커 모델? (빈 칸 = 기본값)"` → `gemini_model`
+6. `"리포트 작성자 모델? (빈 칸 = 기본값)"` → `report_writer_model`
+7. `"추가 directive (선택, 빈 칸 가능)"` → `directive`
+8. `"관련 task id 목록, 쉼표 구분 (선택, 빈 칸 가능)"` → `related_tasks_raw`
+9. `"clarification-response 파일 경로 (follow-up 시에만, 빈 칸 가능)"` → `clarification_response_path`
+
+For prompts whose target worker is NOT in the resolved workers list (after override), skip the prompt and present a single line such as `gemini-model 생략 (workers에 gemini 없음)`.
+
+## Step 6.5: Confirm selections before rendering
+
+Before calling `prepare_task_bundle`, echo the resolved selections back to the user in a compact block so they can verify what will be passed. Show the **effective** values, not the raw input — i.e. when the user left a field blank, display `default` (and where known, the actual default such as `opus` / `sonnet`). Example for an `implementation` run:
+
+```
+선택 확인:
+  task-type     : implementation
+  task-key      : <group>/<id>
+  executor      : codex
+  workers       : (프로필 기본 — executor + verifier 2 + report-writer)
+  lead-model    : default (opus)
+  codex-model   : gpt-5.5-high           ← executor model
+  claude-model  : default (sonnet)       ← verifier
+  gemini-model  : default (auto)         ← verifier
+  report-writer : default (opus)
+  directive     : (none)
+  approved-plan : <abs path>
+```
+
+Then `AskUserQuestion`: `"이대로 진행할까요?"` with options `Proceed` / `Edit`. On `Edit`, return to the relevant Step 6 sub-prompt.
 
 ## Step 7: Call `prepare_task_bundle` directly
 
@@ -182,7 +226,7 @@ out = prepare_task_bundle(PrepareInputs(
     task_type="<task-type>",
     brief_path=brief_abs,
     directive="<directive or empty>",
-    workers_override="<workers csv or empty>",
+    workers_override="<comma-separated worker list, or empty for profile default; MUST be empty for implementation>",
     lead_model="...", claude_model="...", codex_model="...",
     gemini_model="...", report_writer_model="...",
     related_tasks_raw="...",

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

@@ -116,6 +116,32 @@ print(result)
 PY
 ```
 
+## Step 4.5 (optional): customise worktree sync dirs
+
+Each okstra run provisions a task-scoped git worktree under
+`~/.okstra/worktrees/.../`. A small set of project-root-relative
+directories is symlinked from the main checkout into that worktree so
+every task sees the shared state. The built-in default is
+`.project-docs`, `.scratch`, `graphify-out`, `.claude`.
+
+To override per-project, add a `worktreeSyncDirs` array to
+`project.json`. Empty array disables the feature; the field is
+preserved across the runtime's auto-upserts (only `projectId`,
+`projectRoot`, `createdAt`, `updatedAt` are runtime-owned).
+
+```json
+{
+  "projectId": "...",
+  "projectRoot": "...",
+  "worktreeSyncDirs": [".project-docs", ".scratch", ".claude", "my-custom-dir"]
+}
+```
+
+Resolution precedence: `OKSTRA_WORKTREE_SYNC_DIRS` env var → this
+field → built-in default. Only edit when defaults don't cover the
+project's working files (e.g. additional cache or local-config dirs
+that must follow the executor into the worktree).
+
 ## Step 5: Verify
 
 ```bash

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

@@ -333,15 +333,16 @@ Empty-state placeholder, copy verbatim when nothing else applies:
 규칙:
 
 - 각 row의 `Auto-spawn?` 값이 `yes` 이면 Phase 7 의 `scripts/okstra-spawn-followups.py` 가 자동으로 후속 task 디렉터리(`tasks/<TASK_GROUP>/<New Task ID>/`)와 `task-manifest.json` (status: `todo`), stub task-brief 를 생성합니다. `no` 이면 사람이 따로 결정합니다.
+- `Ticket ID` 는 본 보고서 상단 `Ticket Coverage` 규칙과 동일합니다. 후속 작업이 특정 외부 ticket(Jira/Linear/이슈 트래커 등)이나 본 보고서의 ticket 인덱스에 묶이면 그 키를 적고, 매핑이 없으면 `Task ID` 폴백 값을 prefix 없이 적습니다(예: `8852`). 어느 쪽으로도 식별 불가하면 `unknown`.
 - `New Task ID` 는 알파숫자·하이픈만 사용하는 짧은 slug 입니다 (예: `8852-followup-logs`). 같은 task-group 안에서 유일해야 합니다.
 - `Suggested task-type` 은 `requirements-discovery` / `error-analysis` / `implementation-planning` / `implementation` / `final-verification` / `release-handoff` 중 하나.
 - `Scope` 는 영향 파일·영역을 콤마 또는 한 줄로 적습니다.
 - `Reason / Why deferred` 는 본 run 에서 처리하지 못한 이유를 한 두 문장으로 적습니다. "시간이 없어서" 같은 모호한 사유는 거절됩니다.
 - 동일 follow-up 이 여러 run 에 걸쳐 등장하면 `New Task ID` 를 동일하게 유지하여 중복 spawn 을 방지합니다 (script 가 기존 디렉터리 존재 여부로 idempotent 처리).
 
-| ID | Origin | New Task ID | Title | Suggested task-type | Scope (files/areas) | Reason / Why deferred | Priority (P0/P1/P2) | Auto-spawn? |
-|----|--------|-------------|-------|---------------------|---------------------|------------------------|---------------------|-------------|
-| FU-001 | `<out-of-plan / verifier-concern / scope-boundary / open-question / manual>` | `<new-task-id-slug>` | <한 줄 제목> | `<task-type>` | `<files / areas>` | <한 두 문장 사유> | `P1` | `yes` |
+| ID | Ticket ID | Origin | New Task ID | Title | Suggested task-type | Scope (files/areas) | Reason / Why deferred | Priority (P0/P1/P2) | Auto-spawn? |
+|----|-----------|--------|-------------|-------|---------------------|---------------------|------------------------|---------------------|-------------|
+| FU-001 | `<TICKET-or-fallback>` | `<out-of-plan / verifier-concern / scope-boundary / open-question / manual>` | `<new-task-id-slug>` | <한 줄 제목> | `<task-type>` | `<files / areas>` | <한 두 문장 사유> | `P1` | `yes` |
 
 빈 상태 예시 (해당 없음):