okstra 0.1.0

package/runtime/python/okstra_token_usage/collect.py

@@ -0,0 +1,161 @@
+"""Top-level orchestrator that walks team-state and gathers all worker usage."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from .blocks import na_block, usage_block
+from .claude import claude_session_totals, find_claude_team_sessions
+from .codex import codex_session_total, find_codex_session
+from .gemini import find_gemini_session, gemini_session_total
+from .paths import claude_project_dir, utc_now
+from .pricing import codex_cost_usd, gemini_cost_usd
+
+
+def collect(team_state_path: Path, project_root: Path | None = None) -> dict:
+    state = json.loads(team_state_path.read_text())
+    cwd = project_root or _infer_project_root(team_state_path, state)
+    task_key = state.get("taskKey", "")
+    # Prefer the team name actually persisted in team-state (set during Phase 3
+    # when TeamCreate succeeded); only fall back to the `okstra-<task-id>`
+    # convention if team-state did not record one. Matching downstream is
+    # case-insensitive so either casing works.
+    state_team = (state.get("team") or {})
+    team_name = state_team.get("teamName") or ""
+    if not team_name:
+        task_id = task_key.rsplit(":", 1)[-1] if task_key else ""
+        team_name = f"okstra-{task_id}" if task_id else ""
+    lead_sid = (state.get("lead") or {}).get("sessionId")
+
+    # 1) Claude sessions (lead + claude-side workers).
+    claude_sessions = find_claude_team_sessions(cwd, team_name, lead_sid)
+    by_agent: dict[str, tuple[str, Path]] = {}
+    lead_path: Path | None = None
+    for sid, path in claude_sessions.items():
+        if sid == lead_sid:
+            lead_path = path
+            continue
+        # Read agentName lazily.
+        totals = claude_session_totals(path)
+        agent = totals.get("agentName")
+        if agent:
+            by_agent[agent] = (sid, path)
+
+    # Lead.
+    if lead_path is not None:
+        totals = claude_session_totals(lead_path)
+        state["leadUsage"] = usage_block(totals, source="claude-jsonl")
+        state["leadUsage"]["sessionId"] = lead_sid
+    else:
+        state["leadUsage"] = na_block(
+            f"lead session jsonl not found under {claude_project_dir(cwd)} (sessionId={lead_sid})"
+        )
+
+    # Workers.
+    for worker in state.get("workers", []):
+        worker_id = worker.get("workerId")
+        agent = worker.get("agent")
+        # Subagent agentName convention: workerId itself is "claude" but agentName is "claude-worker"; report-writer == "report-writer".
+        agent_name_candidates = []
+        if worker_id:
+            agent_name_candidates.append(worker_id)
+            if not worker_id.endswith("-worker") and worker_id != "report-writer":
+                agent_name_candidates.append(f"{worker_id}-worker")
+
+        # Claude wrapper jsonl (also for codex/gemini-worker, since these are Claude subagents).
+        wrapper = None
+        for cand in agent_name_candidates:
+            if cand in by_agent:
+                wrapper = by_agent[cand]
+                break
+        if wrapper is None:
+            worker["usage"] = na_block(f"no Claude subagent jsonl found with agentName matching {agent_name_candidates}")
+            continue
+        sid, path = wrapper
+        totals = claude_session_totals(path)
+        block = usage_block(totals, source="claude-jsonl")
+        block["sessionId"] = sid
+
+        # For codex/gemini workers, also try to find the underlying CLI session
+        # within the wrapper subagent's time window.
+        wrapper_start = totals.get("startedAt") or ""
+        wrapper_end = totals.get("endedAt") or ""
+        if agent in ("codex", "gemini"):
+            if agent == "codex":
+                cli = find_codex_session(cwd, wrapper_start, wrapper_end)
+                cli_totals = codex_session_total(cli) if cli else None
+            else:
+                cli = find_gemini_session(cwd, wrapper_start, wrapper_end)
+                cli_totals = gemini_session_total(cli) if cli else None
+            if cli is None:
+                block["cliNote"] = f"{agent} CLI session not found in wrapper window (fallback or never invoked)"
+            else:
+                block["cliSessionPath"] = str(cli)
+                if cli_totals.get("model"):
+                    block["cliModel"] = cli_totals["model"]
+                if cli_totals.get("available"):
+                    block["cliTotalTokens"] = cli_totals["totalTokens"]
+                    if agent == "codex":
+                        cost = codex_cost_usd(
+                            cli_totals.get("model"),
+                            cli_totals.get("inputTokens", 0) or 0,
+                            cli_totals.get("cachedInputTokens", 0) or 0,
+                            cli_totals.get("outputTokens", 0) or 0,
+                        )
+                    else:
+                        cost = gemini_cost_usd(
+                            cli_totals.get("model"),
+                            cli_totals.get("inputTokens", 0) or 0,
+                            cli_totals.get("outputTokens", 0) or 0,
+                        )
+                    if cost is not None:
+                        block["cliEstimatedCostUsd"] = cost
+                else:
+                    block["cliNote"] = f"{agent} CLI session found but no usage recorded (likely errored before completion)"
+        worker["usage"] = block
+
+    # Aggregate summary.
+    lead = state.get("leadUsage") or {}
+    workers = state.get("workers", [])
+    lead_total = lead.get("totalTokens", 0) or 0
+    lead_billable = lead.get("billableEquivalentTokens", 0) or 0
+    lead_cost = lead.get("estimatedCostUsd", 0) or 0
+    worker_total = sum((w.get("usage") or {}).get("totalTokens", 0) or 0 for w in workers)
+    worker_billable = sum((w.get("usage") or {}).get("billableEquivalentTokens", 0) or 0 for w in workers)
+    worker_cost = sum((w.get("usage") or {}).get("estimatedCostUsd", 0) or 0 for w in workers)
+    cli_cost = sum((w.get("usage") or {}).get("cliEstimatedCostUsd", 0) or 0 for w in workers)
+    state["usageSummary"] = {
+        "leadTotalTokens": lead_total,
+        "workerTotalTokens": worker_total,
+        "grandTotalTokens": lead_total + worker_total,
+        "leadBillableEquivalentTokens": lead_billable,
+        "workerBillableEquivalentTokens": worker_billable,
+        "grandBillableEquivalentTokens": lead_billable + worker_billable,
+        "estimatedCostUsd": {
+            "lead": round(lead_cost, 4),
+            "claudeWorkers": round(worker_cost, 4),
+            "cliWorkers": round(cli_cost, 4),
+            "grandTotal": round(lead_cost + worker_cost + cli_cost, 4),
+        },
+        "collectedAt": utc_now(),
+        "teamName": team_name,
+        "sessionsFound": len(claude_sessions),
+        "definitions": {
+            "totalTokens": "Sum of input + output + cache_creation + cache_read tokens (raw processed volume; matches Anthropic API breakdown). Cache reads are 95%+ in long sessions.",
+            "billableEquivalentTokens": "Tokens normalized to base-input-price units (cache_creation x1.25, cache_read x0.1, output x5). Useful when comparing sessions across models or to gauge cost.",
+            "estimatedCostUsd": "USD cost using public list pricing for the model recorded in the session. cliWorkers covers Codex/Gemini CLI calls billed under those providers.",
+        },
+    }
+    return state
+
+
+def _infer_project_root(team_state_path: Path, state: dict) -> Path:
+    rel = state.get("runDirectoryPath") or ""
+    p = team_state_path.resolve().parent
+    while p != p.parent:
+        if rel and (p / rel).is_dir():
+            return p
+        if (p / ".project-docs").is_dir():
+            return p
+        p = p.parent
+    raise SystemExit(f"could not infer project root from {team_state_path}")
+

package/runtime/python/okstra_token_usage/gemini.py

@@ -0,0 +1,77 @@
+"""Gemini CLI session collectors."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from .paths import GEMINI_TMP
+
+
+def gemini_session_total(json_path: Path) -> dict:
+    try:
+        data = json.loads(json_path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return {"totalTokens": 0, "available": False}
+    msgs = data.get("messages") or []
+    total = 0
+    inp = out = cached = thoughts = tool = 0
+    model = None
+    for m in msgs:
+        tok = m.get("tokens") or {}
+        total += tok.get("total", 0) or 0
+        inp += tok.get("input", 0) or 0
+        out += tok.get("output", 0) or 0
+        cached += tok.get("cached", 0) or 0
+        thoughts += tok.get("thoughts", 0) or 0
+        tool += tok.get("tool", 0) or 0
+        if model is None and m.get("model"):
+            model = m["model"]
+    return {
+        "totalTokens": total,
+        "inputTokens": inp,
+        "outputTokens": out,
+        "cachedTokens": cached,
+        "thoughtsTokens": thoughts,
+        "toolTokens": tool,
+        "model": model,
+        "startedAt": data.get("startTime"),
+        "endedAt": data.get("lastUpdated"),
+        "available": True,
+    }
+
+
+def find_gemini_session(project_root: Path, started_at: str, ended_at: str) -> Path | None:
+    """Find the gemini chat session whose first user message references the project."""
+    if not GEMINI_TMP.is_dir() or not started_at or not ended_at:
+        return None
+    project_str = str(project_root)
+    candidates: list[tuple[str, Path]] = []
+    for p in GEMINI_TMP.glob("*/chats/session-*.json"):
+        try:
+            data = json.loads(p.read_text())
+        except (OSError, json.JSONDecodeError):
+            continue
+        start = data.get("startTime") or ""
+        if not (started_at <= start <= ended_at):
+            continue
+        # Match by content: first user message should mention project root or task path.
+        msgs = data.get("messages") or []
+        for m in msgs:
+            if m.get("type") != "user":
+                continue
+            content = m.get("content") or []
+            text = ""
+            if isinstance(content, list):
+                for block in content:
+                    if isinstance(block, dict) and block.get("text"):
+                        text = block["text"]
+                        break
+            elif isinstance(content, str):
+                text = content
+            if project_str in text:
+                candidates.append((start, p))
+            break
+    if not candidates:
+        return None
+    candidates.sort()
+    return candidates[-1][1]
+

package/runtime/python/okstra_token_usage/jsonl_io.py

@@ -0,0 +1,18 @@
+"""JSONL reading helpers used by all session collectors."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Iterable
+
+
+def iter_jsonl(path: Path) -> Iterable[dict]:
+    with path.open() as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                yield json.loads(line)
+            except json.JSONDecodeError:
+                continue

package/runtime/python/okstra_token_usage/paths.py

@@ -0,0 +1,22 @@
+"""Filesystem locations for agent session transcripts and time helpers."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+HOME = Path.home()
+CLAUDE_PROJECTS = HOME / ".claude" / "projects"
+CODEX_SESSIONS = HOME / ".codex" / "sessions"
+GEMINI_TMP = HOME / ".gemini" / "tmp"
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def claude_project_dir(cwd: Path) -> Path:
+    # Claude Code encodes cwd by replacing "/" with "-" (leading slash → leading "-").
+    encoded = "-" + str(cwd).strip("/").replace("/", "-")
+    return CLAUDE_PROJECTS / encoded
+

package/runtime/python/okstra_token_usage/pricing.py

@@ -0,0 +1,71 @@
+"""Public list pricing tables and per-provider cost helpers."""
+from __future__ import annotations
+
+
+# Public list pricing (USD per 1M tokens). Used for cost estimation only.
+# Update when Anthropic / OpenAI / Google change pricing.
+# Anthropic billing ratios relative to base input: cache_creation=1.25x, cache_read=0.1x, output=5x.
+CLAUDE_PRICING = {
+    # model substring -> (input, cache_creation, cache_read, output) USD/1M
+    "opus-4": (15.0, 18.75, 1.50, 75.0),
+    "sonnet-4": (3.0, 3.75, 0.30, 15.0),
+    "haiku-4": (1.0, 1.25, 0.10, 5.0),
+    "opus-3": (15.0, 18.75, 1.50, 75.0),
+    "sonnet-3": (3.0, 3.75, 0.30, 15.0),
+    "haiku-3": (0.80, 1.0, 0.08, 4.0),
+}
+
+CODEX_PRICING = {
+    # model substring -> (input USD/1M, cached_input USD/1M, output USD/1M)
+    "gpt-5": (1.25, 0.125, 10.0),
+    "gpt-4": (2.50, 0.625, 10.0),
+}
+
+GEMINI_PRICING = {
+    # model substring -> (input USD/1M, output USD/1M); cached not separately priced for short runs
+    "pro": (1.25, 5.0),
+    "flash": (0.075, 0.30),
+    "auto": (1.25, 5.0),  # treat unknown as pro
+}
+
+
+def _match_pricing(model: str | None, table: dict) -> tuple | None:
+    if not model:
+        return None
+    m = model.lower()
+    for key, val in table.items():
+        if key in m:
+            return val
+    return None
+
+
+def claude_billable_equivalent(input_t: int, cache_create_t: int, cache_read_t: int, output_t: int) -> int:
+    """Sum normalized to base-input units (cache_creation 1.25x, cache_read 0.1x, output 5x)."""
+    return int(round(input_t + 1.25 * cache_create_t + 0.1 * cache_read_t + 5.0 * output_t))
+
+
+def claude_cost_usd(model: str | None, input_t: int, cache_create_t: int, cache_read_t: int, output_t: int) -> float | None:
+    p = _match_pricing(model, CLAUDE_PRICING)
+    if p is None:
+        return None
+    pi, pcc, pcr, po = p
+    return round((input_t * pi + cache_create_t * pcc + cache_read_t * pcr + output_t * po) / 1_000_000, 4)
+
+
+def codex_cost_usd(model: str | None, input_t: int, cached_input_t: int, output_t: int) -> float | None:
+    p = _match_pricing(model, CODEX_PRICING)
+    if p is None:
+        return None
+    pi, pci, po = p
+    # Codex `input_tokens` already includes cached; subtract cached and price the rest at full input.
+    fresh = max(0, input_t - cached_input_t)
+    return round((fresh * pi + cached_input_t * pci + output_t * po) / 1_000_000, 4)
+
+
+def gemini_cost_usd(model: str | None, input_t: int, output_t: int) -> float | None:
+    p = _match_pricing(model, GEMINI_PRICING)
+    if p is None:
+        return None
+    pi, po = p
+    return round((input_t * pi + output_t * po) / 1_000_000, 4)
+

package/runtime/python/okstra_token_usage/report.py

@@ -0,0 +1,64 @@
+"""Final-report substitution helpers (writes Phase 7 placeholders into final-report.md)."""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def _format_int(n) -> str:
+    try:
+        return f"{int(n):,}"
+    except (TypeError, ValueError):
+        return "0"
+
+
+def _format_usd(v) -> str:
+    try:
+        return f"${float(v):.2f}"
+    except (TypeError, ValueError):
+        return "$0.00"
+
+
+def substitute_final_report(report_path: Path, state: dict) -> int:
+    """Replace token-usage placeholders in the final report file with concrete
+    values from the freshly computed usageSummary.
+
+    Returns the number of placeholder occurrences replaced. If the report file
+    does not exist, returns -1 without raising. If any required placeholder is
+    still present after substitution attempts (e.g. usageSummary missing), the
+    function still writes what it can and returns the count.
+    """
+    if not report_path.is_file():
+        return -1
+
+    summary = state.get("usageSummary") or {}
+    cost = summary.get("estimatedCostUsd") or {}
+    lead_cost = cost.get("lead") or 0
+    worker_cost = cost.get("claudeWorkers") or 0
+    cli_cost = cost.get("cliWorkers") or 0
+    grand_cost = lead_cost + worker_cost  # CLI tracked on its own row per template
+
+    mapping = {
+        "{{LEAD_TOTAL_TOKENS}}": _format_int(summary.get("leadTotalTokens", 0)),
+        "{{LEAD_BILLABLE_TOKENS}}": _format_int(summary.get("leadBillableEquivalentTokens", 0)),
+        "{{LEAD_COST_USD}}": _format_usd(lead_cost),
+        "{{WORKER_TOTAL_TOKENS}}": _format_int(summary.get("workerTotalTokens", 0)),
+        "{{WORKER_BILLABLE_TOKENS}}": _format_int(summary.get("workerBillableEquivalentTokens", 0)),
+        "{{WORKER_COST_USD}}": _format_usd(worker_cost),
+        "{{GRAND_TOTAL_TOKENS}}": _format_int(summary.get("grandTotalTokens", 0)),
+        "{{GRAND_BILLABLE_TOKENS}}": _format_int(summary.get("grandBillableEquivalentTokens", 0)),
+        "{{GRAND_COST_USD}}": _format_usd(grand_cost),
+        "{{CLI_COST_USD}}": _format_usd(cli_cost),
+    }
+
+    text = report_path.read_text()
+    replaced = 0
+    for needle, value in mapping.items():
+        count = text.count(needle)
+        if count:
+            text = text.replace(needle, value)
+            replaced += count
+
+    if replaced:
+        report_path.write_text(text)
+    return replaced
+

package/runtime/templates/prd/brief.template.md

@@ -0,0 +1,273 @@
+# OKSTRA Task Brief
+
+<!--
+이 brief은 okstra 워커(Claude/Codex/Gemini)가 코드베이스/도메인 사전지식 없이 분석할 수 있도록 준비하는 단일 source-of-truth 문서입니다.
+
+원칙:
+1. 워커는 외부 링크에 접근할 수 없음 → 모든 1차 증거는 inline으로 박을 것 (fenced code block).
+2. 워커는 도메인 용어를 모름 → Domain Glossary로 핵심 용어를 사전 정의.
+3. 운영자(operator)용 정보(okstra.sh 명령, working directory)는 brief에 두지 말 것 — 별도 runbook으로.
+4. Task Type에 따라 작성해야 할 섹션이 다름 → 해당 태스크의 conditional 블록을 채울 것.
+5. 비어 있는 섹션은 `_N/A — <reason>_`로 명시. 침묵은 워커 혼란의 원인.
+-->
+
+## Identity
+
+| Field | Value |
+|-------|-------|
+| Brief Title | `<task-group>-<TASK-ID>-<short-slug>` |
+| Project ID | `<project-id>` |
+| Task Group | `<task-group>` |
+| Task ID | `<TASK-ID>` |
+| Task Type | `requirements-discovery` \| `error-analysis` \| `implementation-planning` \| `final-verification` |
+| Issue / Ticket | `<TASK-ID> · <title in original language> (English: <translation if non-English>)` |
+| Requested Outcome | <한 문장. 이 run이 산출해야 할 핵심 결과물> |
+
+---
+
+## Request Summary
+
+- **What is being requested or changed?**
+  <한 문단 또는 bullet 3-5개>
+- **Why now?**
+  <비즈니스/기술 트리거. 마감일, 인시던트, 의존 태스크 등>
+- **New / Continuation / Reopened?**
+  <One of the three + 직전 run 식별자(있다면)>
+- **What decision should this run produce?**
+  <이 run이 답해야 할 핵심 결정 1-3개. 모호하면 워커가 산만해짐>
+
+---
+
+## Inline Evidence
+
+<!--
+워커는 외부 URL/Notion/Linear/Slack에 접근할 수 없습니다. 1차 증거는 모두 여기에 inline 박을 것.
+-->
+
+### Symptom / Sample Payload
+
+```
+<관찰된 현상, 응답 페이로드 샘플, UI 스크린샷 caption 등 — 텍스트로>
+```
+
+### Logs / Stack Trace (해당되는 경우)
+
+```
+<로그 발췌. 민감정보는 마스킹>
+```
+
+### Relevant Code Excerpts
+
+```typescript
+// path: src/domains/upload/dto/upload-job.view.ts:23-45
+<코드 발췌 — 워커가 파일 전체를 읽지 않아도 핵심을 파악할 수 있어야 함>
+```
+
+### External Doc Excerpts (Notion/Linear/Confluence 발췌)
+
+> <원문 인용. 링크는 보조이고 인용이 본체>
+> -- Source: <doc title + section>
+
+---
+
+## Domain Glossary
+
+<!--
+Codex/Gemini는 이 코드베이스를 모릅니다. 핵심 용어 5-15개를 한 문장씩 정의.
+없는 용어를 워커가 추측하면 분석 품질이 즉시 떨어집니다.
+-->
+
+| Term | Definition |
+|------|-----------|
+| `<도메인 용어 1>` | <1-2 문장 정의> |
+| `<도메인 용어 2>` | <1-2 문장 정의> |
+| `<코드 식별자 1>` | <역할 + 위치 + 다른 entity와의 관계> |
+
+---
+
+## Current Context
+
+- **Current behavior or state**:
+  <지금 시스템이 어떻게 동작하는가>
+- **Desired behavior or outcome**:
+  <어떻게 동작해야 하는가>
+- **Existing related implementation**:
+  - `<file-path>:<line-range>` — <역할 한 줄>
+- **Related code paths** (참조용 — 직접 발췌는 Inline Evidence에):
+  - `<path>`
+  - `<path>`
+
+---
+
+## Out of Scope
+
+<!--
+명시적 제외 목록. 워커 scope-creep 방지의 핵심.
+-->
+
+이 run에서는 **다루지 않을** 것들:
+
+- <out-of-scope item 1 + 제외 이유>
+- <out-of-scope item 2 + 제외 이유>
+- <별도 ticket/run으로 다룰 항목 — ticket ID 명시>
+
+---
+
+## Task-Type Focus
+
+<!--
+아래 두 블록 중 현재 task-type에 해당하는 것만 채우고, 나머지는 삭제하세요.
+-->
+
+### If `requirements-discovery`
+
+- **Why might this be a bugfix?**
+  <증거 또는 "weak signal — none observed">
+- **Why might this be a feature/improvement?**
+  <증거>
+- **Why might this be a refactor/ops-change?**
+  <증거>
+- **Classification blockers** — 무엇이 분류 확신을 막고 있는가?
+  <evidence gap을 구체적으로>
+
+### If `error-analysis`
+
+- **Symptom** — 사용자/시스템이 무엇을 관찰하는가?
+- **Reproduction Steps** — 1-2-3 형식. 환경/사전조건 명시.
+  ```
+  1. <env: staging | local | prod>
+  2. <action>
+  3. <action>
+  4. Expected: <…> / Actual: <…>
+  ```
+- **Frequency** — 항상 / 간헐적 / 특정 조건에서만 / 1회성?
+- **Blast Radius** — 영향받는 사용자/요청/data 범위
+- **Suspected Cause(s)** — 현재까지의 가설. 각각 신뢰도(High/Med/Low)와 근거.
+- **What has been ruled out** — 이미 검증한 false leads (워커가 같은 길 가지 않게)
+
+---
+
+## Constraints and Risks
+
+- **Business constraints**: <e.g. 개인정보, SLA — 외부 승인/권한 항목은 적지 말 것 (사용자가 모든 권한을 가진다고 가정)>
+- **Technical constraints**: <e.g. backward-compat, 기존 client, schema>
+- **Delivery constraints**: <마감, 의존 배포, 롤아웃 게이트 — 단, 외부 승인 대기·권한 확인은 일정 요소로 적지 말 것>
+- **Approval / review checkpoints**: _N/A — 사용자가 모든 권한·승인 권한을 보유한다고 가정 (okstra 기본 규칙). 정말로 외부 차단 요소가 있을 때만 구체적으로 기술._
+- **Known assumptions**: <명시적 가정 — 워커가 검증할 항목>
+- **Open uncertainties**: <확인 필요한 것 — 답이 나오면 결정이 잠금 해제됨. 외부 권한·승인 관련 항목은 제외>
+
+---
+
+## Configuration / Deployment Context
+
+<!--
+이 섹션은 *해당되는 경우에만* 채우세요. DTO 변경, 순수 로직 수정, 문서 작업 등은 보통 _N/A_입니다.
+무관할 때는 본 섹션 전체를 다음 한 줄로 대체:
+
+  _N/A — this task does not touch config or deployment._
+-->
+
+- **Config files in scope**: `<path>` — <어떤 키가 관련>
+- **Current observed values**: <key=value, 출처 명시>
+- **Expected values / invariants**: <변하면 안 되는 것 + 변해야 하는 것>
+- **Deployment manifests in scope**: `<helm chart / k8s manifest / terraform path>`
+- **Rollout invariants**: <e.g. zero-downtime, version skew window>
+
+---
+
+## External Resource Hints (for Lead pre-fetch)
+
+<!--
+okstra Lead가 워커 프롬프트에 inline으로 박아야 할 외부 자원 목록.
+워커는 MCP/외부 도구에 직접 접근하지 않으므로 Lead가 사전에 snapshot해서 prompt에 embed합니다.
+-->
+
+| Resource | Type | Why needed |
+|----------|------|-----------|
+| `<table-name>` | MySQL schema | <어느 분석에서 schema 검증 필요> |
+| `<library@version>` | Library docs (`mcp__test-context7`) | <API 시그니처 확인용> |
+| `<aws-doc-keyword>` | AWS knowledge base | <설계 검증용> |
+| `/Volumes/.../app/<sibling-project>/<path>` | Cross-project file | <reference impl> |
+
+자원 없음이 명확하면 본 섹션을 `_N/A_`로 표시.
+
+---
+
+## Related Tasks
+
+<!--
+관계 라벨을 반드시 명시: blocker | blocked-by | sibling | follow-up | duplicate | shares-codepath
+-->
+
+| Task | Relation | Note |
+|------|----------|------|
+| `DEV-XXXX` | `sibling` | 같은 epic, 같은 코드베이스, 동시 변경 가능성 |
+| `DEV-YYYY` | `blocker` | 이 task는 DEV-YYYY 완료 후에만 시작 가능 |
+
+---
+
+## Definition of Done (for this run)
+
+<!--
+Requested Outcome은 큰 그림. 여기서는 "이 run의 산출물이 충족해야 할 검증 가능한 조건"을 적습니다.
+-->
+
+이 run의 final report는 다음을 모두 충족해야 합니다:
+
+- [ ] <결정 항목 1에 대한 명시적 답변 또는 "결정 불가 + 이유">
+- [ ] <결정 항목 2에 대한 명시적 답변>
+- [ ] <남은 blocking question 목록>
+- [ ] <recommended next phase + reasoning>
+
+---
+
+## Questions for Workers
+
+<!--
+P0(반드시 답해야 함) / P1(가능하면 답) / P2(보너스)로 우선순위 명시.
+-->
+
+1. **[P0]** <핵심 질문 1>
+2. **[P0]** <핵심 질문 2>
+3. **[P1]** <보조 질문>
+4. **[P2]** <탐색적 질문>
+
+---
+
+## Expected Outputs
+
+| Category | Expected content |
+|----------|-----------------|
+| Root cause / plan options / blockers | <ranked list of options or candidates> |
+| Missing information | <what additional discovery is required> |
+| Risks | <ordered by severity> |
+| Recommended next actions | <phase routing + concrete next step> |
+
+---
+
+## Notes for Lead (synthesis emphasis)
+
+<!--
+워커 셀렉션(어느 모델을 쓸지)은 task-manifest.json의 recommendedWorkers에서 자동 결정되므로 여기에 적지 마세요.
+이 섹션은 *합성 시 강조점*만 다룹니다.
+-->
+
+- **Synthesis priority**: <e.g. 안전성 vs 속도, public/private 경계 정확성, backward compat>
+- **Where worker disagreement matters most**: <consensus가 가장 중요한 지점>
+- **Where reduced confidence is acceptable**: <탐색 영역 — 가설만 나와도 충분>
+
+---
+
+## Brief Hygiene Checklist
+
+작성 후 자가 점검:
+
+- [ ] 모든 외부 링크에 대해 inline 발췌가 박혀 있다
+- [ ] Domain Glossary에 코드베이스 무지식 워커가 알아야 할 용어가 모두 있다
+- [ ] Out of Scope가 명시적으로 적혀 있다
+- [ ] Task-Type Focus의 해당 블록만 남아 있다 (다른 블록은 삭제됨)
+- [ ] error-analysis라면 Reproduction Steps가 채워져 있다
+- [ ] Definition of Done이 검증 가능한 체크리스트 형태다
+- [ ] Configuration / Deployment 섹션은 해당 시에만 내용이 있고, 무관 시 `_N/A_`로 닫혀 있다
+- [ ] 한글/영문/원어 ticket title 모두 식별 가능하다
+- [ ] Related Tasks에 관계 라벨이 명시되어 있다