okstra 0.34.1 → 0.36.1

package/runtime/skills/okstra-report-writer/SKILL.md

@@ -49,8 +49,12 @@ The prompt MUST include, in this order at the top:
 7. The full `[Required reading]` clause (see [okstra-team-contract](../okstra-team-contract/SKILL.md)) including `schemas/final-report-v1.0.schema.json` and `templates/reports/final-report.template.md` (template is read-only — the worker writes the data.json that drives it).
 8. The verbatim `## Available MCP Servers` block from the task brief, if present.
 9. The convergence classifications (Full/Partial/Contested/Worker-Unique), the round history table (`roundHistory[]`), the `round2SkippedReason` value, and pointers to all worker result files under `worker-results/`. The report-writer worker must reproduce a Round History sub-table in Section 1 of the final report so the reader can see which rounds executed, queue sizes, and why Round 2 was (or was not) skipped.
-10. For implementation-planning runs: a literal block listing the 8 required English section headings the validator scans for (`Option Candidates`, `Trade-off`, `Recommended Option`, `Stepwise Execution Order`, `Dependency`, `Validation Checklist`, `Rollback`, `User Approval Request`). The writer must use these exact substrings as section headings (Korean translation in parentheses is allowed).
-11. An explicit instruction: `You are the author of TWO files: (a) the final-report data.json at <Result Path>, (b) the worker-results audit file at <Worker Result Path>. After writing the data.json, invoke "python3 scripts/okstra-render-final-report.py <Result Path>" via Bash so the markdown sibling is rendered before you return. Do not return the report inline. The validator fails the run when (a)'s schema validation fails, when the rendered markdown is absent, or when (b) is missing.`
+10. `**Report Language:** <en|ko>` — must be either `en` or `ko`; `auto`
+    has been resolved by the lead from project.json / global config
+    before the dispatch is constructed. The worker copies this verbatim
+    into `data.json.meta.reportLanguage`.
+11. For implementation-planning runs: a literal block listing the 8 required English section headings the validator scans for (`Option Candidates`, `Trade-off`, `Recommended Option`, `Stepwise Execution Order`, `Dependency`, `Validation Checklist`, `Rollback`, `User Approval Request`). The writer must use these exact substrings as section headings (Korean translation in parentheses is allowed).
+12. An explicit instruction: `You are the author of TWO files: (a) the final-report data.json at <Result Path>, (b) the worker-results audit file at <Worker Result Path>. After writing the data.json, invoke "python3 scripts/okstra-render-final-report.py <Result Path>" via Bash so the markdown sibling is rendered before you return. Do not return the report inline. The validator fails the run when (a)'s schema validation fails, when the rendered markdown is absent, or when (b) is missing.`
 
 ### Resume-safe dispatch
 
@@ -163,26 +167,32 @@ Table Generation Rules:
 
 Place this section immediately after the execution status table.
 
+Example (English mode shown — the renderer substitutes Korean when `meta.reportLanguage = "ko"`):
+
 ```markdown
-### 토큰 사용량 요약
+### Token Usage Summary
 
-| 항목 | 처리 토큰 | 환산 토큰 (input 기준) | 비용 (USD) |
-|------|-----------|------------------------|------------|
+| Item | Raw tokens | Billable tokens (input-equiv.) | Cost (USD) |
+|------|------------|--------------------------------|------------|
 | Lead | 10,479,327 | 1,769,798 | $26.55 |
-| Worker 합계 | 7,988,699 | 2,075,192 | $25.43 |
-| **전체 합계** | **18,468,026** | **3,844,990** | **$51.97** |
-| Codex/Gemini CLI 추가 비용 |  |  | $0.00 |
+| Worker subtotal | 7,988,699 | 2,075,192 | $25.43 |
+| **Grand total** | **18,468,026** | **3,844,990** | **$51.97** |
+| Codex/Gemini CLI add-on |  |  | $0.00 |
 
-> **읽는 법**: "처리 토큰"은 모델이 실제로 처리한 raw 토큰 합계(input + output + cache_creation + cache_read). 긴 세션에서는 cache_read가 95% 이상을 차지해 숫자가 커 보입니다. "환산 토큰"은 cache_read를 0.1×, cache_creation을 1.25×, output을 5×로 가중한 input-등가 토큰으로, 비용 감각에 가깝습니다. 비용은 공시 가격(Anthropic/OpenAI/Google) 기준 추정치입니다.
+> **How to read**: "Raw tokens" is the total tokens the model actually processed (input + output + cache_creation + cache_read). In long sessions cache_read can account for 95%+ making the number look large. "Billable tokens" weights cache_read at 0.1×, cache_creation at 1.25×, and output at 5× to give an input-equivalent figure closer to actual cost. Costs are estimates based on published Anthropic/OpenAI/Google pricing.
 ```
 
 Token Summary Generation Rules:
 - **You populate the data.json in Phase 6, BEFORE Phase 7 runs the collector.** Set `tokenUsage.lead.totalTokens` / `.billableTokens` / `.costUsd`, the `worker` and `grand` rows, `tokenUsage.cli.costUsd`, and each `executionStatus[].{totalTokens,billableTokens,costUsd,durationMs,cliTotalTokens,cliCostUsd}` to JSON `null`. The renderer emits `--` for nulls; `okstra-token-usage.py --substitute-data` populates them in Phase 7 and re-renders the markdown. Never set these cells to `0`, `"not-collected"`, `"--"`, `"N/A"`, or any other sentinel: nulls are the only valid placeholder, and the substitution step depends on them being null when it runs.
+- Set `meta.reportLanguage` to the resolved `en` or `ko` value passed in
+  **Report Language**. `auto` is forbidden in this field — the lead has
+  already resolved it. The renderer reads this field as SSOT when no
+  CLI `--report-language` flag is given.
 - All values come from `usageSummary` (populated by `scripts/okstra-token-usage.py` at the start of Phase 7). Do not estimate or invent.
 - **Lead** row: `usageSummary.leadTotalTokens` / `usageSummary.leadBillableEquivalentTokens` / `usageSummary.estimatedCostUsd.lead`.
-- **Worker 합계** row: `usageSummary.workerTotalTokens` / `usageSummary.workerBillableEquivalentTokens` / `usageSummary.estimatedCostUsd.claudeWorkers`.
-- **전체 합계** row: `usageSummary.grandTotalTokens` / `usageSummary.grandBillableEquivalentTokens` / sum of `lead + claudeWorkers`.
-- **Codex/Gemini CLI 추가 비용** row: `usageSummary.estimatedCostUsd.cliWorkers`. If 0, still show the row so the reader sees that no CLI work was billed under those providers (or that CLI fallback occurred).
+- **Worker subtotal** (ko: `Worker 합계`) row: `usageSummary.workerTotalTokens` / `usageSummary.workerBillableEquivalentTokens` / `usageSummary.estimatedCostUsd.claudeWorkers`.
+- **Grand total** (ko: `전체 합계`) row: `usageSummary.grandTotalTokens` / `usageSummary.grandBillableEquivalentTokens` / sum of `lead + claudeWorkers`.
+- **Codex/Gemini CLI add-on** (ko: `Codex/Gemini CLI 추가 비용`) row: `usageSummary.estimatedCostUsd.cliWorkers`. If 0, still show the row so the reader sees that no CLI work was billed under those providers (or that CLI fallback occurred).
 - Format tokens with comma separators (e.g., `32,500`); format USD with two decimals (e.g., `$1.43`).
 - If `lead` or any `worker.usage` has `source: "unavailable"`, show `--` for that row and append a one-line note (`reason: <note>`).
 - If pricing for a model is unknown, the script omits `estimatedCostUsd` for that block — show `N/A` in that column and add a note like `pricing missing for model <model>`.
@@ -203,7 +213,7 @@ When the run's `task-type` is `implementation-planning`, the final report MUST c
 | 8 | `User Approval Request` | Satisfied by the top-of-report `## User Approval Request (사용자 승인 게이트)` block. Do NOT recreate a `### 4.5.8 User Approval Request` body stub — the validator now fails reports that contain one. |
 | 9 | `Plan Body Verification` + `Gate result:` | `### Plan Body Verification (계획 본문 검증)` containing a `Gate result:` line — copy `templates/reports/final-report.template.md §4.5.9` verbatim. Validator checks both substrings. |
 
-The Korean translation in parentheses is optional but the English keyword is mandatory. The body of each section is written in Korean per the writing rules below. For non-`implementation-planning` runs, omit this entire block — these headings are NOT validator-checked for other task-types.
+The Korean translation in parentheses is optional but the English keyword is mandatory. The body of each section is written in the Report Language per the writing rules below. For non-`implementation-planning` runs, omit this entire block — these headings are NOT validator-checked for other task-types.
 
 The final-report template `templates/reports/final-report.template.md` Section 4.5 already encodes this contract — copy that block verbatim and fill in.
 
@@ -261,7 +271,17 @@ Section numbering follows `templates/reports/final-report.template.md` exactly
 ### Writing Guidelines
 
 - Write in Markdown. **Prefer tables over prose bullet lists** for any section that enumerates multiple items with the same shape (evidence rows, risks, options, dependencies, rollback steps, follow-ups, open questions). Bullets are reserved for short, single-line standalone statements (e.g., "- 추가 정보 요청 없음."). When the template provides a table form, do NOT degrade it back to bullets in the rendered report.
-- Write the final report body in Korean.
+- Write the final report body in the language passed in **Report Language**
+  above (`en` or `ko`). The template's fixed labels (section asides,
+  empty-states, token summary, column headers, release-handoff labels)
+  are i18n-rendered by `okstra-render-final-report.py` from
+  `templates/reports/i18n/<lang>.json`; do not translate those — focus
+  on the prose you author (Section 1 categories, Section 3 evidence
+  narratives, Section 4 risks, Section 6 recommendations, etc.).
+  Code identifiers, file paths, model names, status tokens, and the
+  validator-checked English substrings (`Option Candidates`,
+  `Verdict Token`, `accepted`/`conditional-accept`/`blocked`, etc.)
+  stay in English regardless of Report Language.
 - Keep technical identifiers such as file paths, code symbols, model names, and status values in their original form when needed.
 - If only one worker is usable, perform a reduced-confidence synthesis
 - If evidence is insufficient, explicitly state "I don't know"
@@ -297,7 +317,7 @@ Persistence steps that must be performed in Phase 7:
 
 ### Response after Persistence
 
-Provide a concise report in Korean covering the following:
+Provide a concise report in the Report Language covering the following:
 - Completion status
 - Final report path
 - Team-state path

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

@@ -18,9 +18,9 @@ Launch an okstra task — gather inputs interactively via the **wizard state mac
 
 ## When NOT to Use
 
-- User explicitly asks to spawn a new terminal / new claude — use `okstra-history` Step 4 (resume command) or instruct them to run `okstra` in another terminal.
-- User wants status only — use `okstra-status`.
-- User wants past runs — use `okstra-history`.
+- User explicitly asks to spawn a new terminal / new claude — use `okstra-inspect history.4` (resume command) or instruct them to run `okstra` in another terminal.
+- User wants status only — use `okstra-inspect status`.
+- User wants past runs — use `okstra-inspect history`.
 
 ## How the wizard talks to you
 
@@ -118,7 +118,7 @@ That is the entire interactive flow. The wizard handles:
 - task-type pick (with `nextRecommendedPhase` surfaced as recommended for existing tasks),
 - brief path (with `유지 / 변경` for existing tasks),
 - base-ref pick + git rev-parse validation (skipped when reusing an active worktree),
-- `implementation`-only sub-flow: approved-plan path (APPROVED marker check) + executor pick,
+- `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + executor pick,
 - `Use defaults / Customize` branch with profile-aware worker/model questions,
 - `release-handoff` PR template override + persist scope,
 - final `Proceed / Edit` confirmation; on `Edit` the wizard asks which step to rewind to and clears every later answer.
@@ -159,6 +159,7 @@ okstra render-bundle \
   --task-brief   "<args.task-brief>" \
   --executor     "<args.executor>" \
   --approved-plan "<args.approved-plan>" \
+  --stage        "<args.stage>" \
   --base-ref     "<args.base-ref>" \
   --workers      "<args.workers>" \
   --directive    "<args.directive>" \
@@ -172,7 +173,7 @@ okstra render-bundle \
   --pr-template-path "<args.pr-template-path>"
 ```
 
-`render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, and the full rendered lead prompt. Parse the labelled lines for `TASK_ROOT` and `INSTRUCTION_SET_DIR`.
+`render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, and the full rendered lead prompt. Parse the labelled lines for `TASK_ROOT` and `INSTRUCTION_SET_PATH`.
 
 The python function underneath is mutex-protected (`~/.okstra/.locks/<task-key>.lock`), writes `run-context-*.json` + `run-inputs-*.json` + all manifests + discovery files, and registers the run in `~/.okstra/recent.jsonl` with status `prepared`.
 
@@ -180,7 +181,7 @@ You can delete the literal state-file path after this point — its job is done.
 
 ## Step 6: Take over as Claude lead
 
-Read `<INSTRUCTION_SET_DIR>/claude-execution-prompt.md` verbatim and enter `Claude lead` mode. The lead prompt itself enumerates every other instruction-set file to load (`analysis-profile.md`, `analysis-material.md`, `reference-expectations.md`, `final-report-template.md`, the run manifest, the team-state artifact, etc.) — follow its order, do not preempt it.
+Read `<INSTRUCTION_SET_PATH>/claude-execution-prompt.md` verbatim and enter `Claude lead` mode. The lead prompt itself enumerates every other instruction-set file to load (`analysis-profile.md`, `analysis-material.md`, `reference-expectations.md`, `final-report-template.md`, the run manifest, the team-state artifact, etc.) — follow its order, do not preempt it.
 
 Then proceed through the phases exactly as the lead prompt directs (Phase 1 context → Phase 2+ worker dispatch → final synthesis → final report).
 
@@ -218,7 +219,7 @@ The scope is held in the wizard state but is not yet exposed by any `okstra wiza
 | `No module named okstra_ctl.wizard` | Install predates wizard module | `npx okstra@latest install` to refresh. |
 | `wizard step` returns `ok: false` repeatedly | User keeps giving invalid answers | Echo the error verbatim and re-prompt the same step — do not advance. |
 | `task root not found for <key>` | catalog entry stale or task-key typo | Restart the wizard (`okstra wizard init`) to refresh the pick list. |
-| `approved plan has no APPROVED marker` | `implementation` without proper approval | Ask the user to add `APPROVED` to the plan, or pick a different task-type. |
+| `approved plan is not yet approved (frontmatter ...)` | `implementation` without proper approval | Ask the user to flip the plan's frontmatter `approved` field to `true` (manual edit or `--approve`), or pick a different task-type. |
 
 ## Output Rules
 

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

@@ -18,7 +18,7 @@ The skill runs as a single Claude lead synthesis (lightweight mode). A `--cross-
 - User wants a single document that summarizes all non-done tasks with effort, risk, and dependencies
 - A `task-group` exists in `.project-docs/okstra/discovery/task-catalog.json` with at least one task whose `workStatus` is not `done`
 
-**Do NOT use** for single-task analysis (use `okstra-status` instead) or when the user wants to actually execute one task (use the parent `okstra` skill).
+**Do NOT use** for single-task analysis (use `okstra-inspect status` instead) or when the user wants to actually execute one task (use the parent `okstra` skill).
 
 ## Trigger Patterns (recognize both)
 
@@ -78,7 +78,7 @@ This skill performs cross-task synthesis (multi-task classification, dependency
 
 Since the `feat(scripts/render): project workStatus fields into task-catalog entries` change (commit `c44c36b`), `workStatus` is also surfaced directly inside each catalog entry — Step 1 still re-reads each `task-manifest.json` because the manifest is authoritative, but no extra fetch is needed beyond that.
 
-For inference rules when `workStatus` is missing or empty, **defer to the inference table in `skills/okstra-status/SKILL.md` ("Step 4 → Inferring workStatus")** instead of duplicating it here. Apply that table to derive a working value, then filter:
+For inference rules when `workStatus` is missing or empty, **defer to the inference table in `skills/okstra-inspect/SKILL.md` (`status.4` → "Default value convention")** instead of duplicating it here. Apply that table to derive a working value, then filter:
 
 - If the resolved value is `done` (set by the user OR inferred via `currentStatus == "completed"` + terminal next-phase) → exclude.
 - Otherwise (`todo` / `in-progress` / `blocked` / `phase-done` / explicit user value / inferred non-done) → include.
@@ -180,7 +180,7 @@ After writing the file, reply briefly:
 
 **The schedule is a client-facing work plan.** It assumes the team has all permissions and can proceed without further approval. Even when the underlying per-task reports flag blocking items, missing approvals, or "사용자 확인 필요 항목", **the schedule MUST NOT surface them**. Those concerns belong in the internal report, not the deliverable.
 
-### Authority & permissions assumption (HARD RULE — schedule sizing)
+### Authority & permissions assumption (schedule sizing)
 
 **Assume the user (and their team) holds full authority and every permission required for every included task.** External approvals, third-party access grants, role/IAM permissions, organisational sign-off, legal/compliance review, vendor coordination, and "verify access exists" steps are treated as already satisfied unless the source per-task report explicitly identifies a concrete external dependency outside the user's control.
 
@@ -232,9 +232,9 @@ Rules for Form B:
 
 The only cross-reference that needs neither inlining nor a glossary entry is a TASK-ID that itself appears in the `## At a Glance` table.
 
-The validator hard-rejects any of these patterns.
+The validator rejects any of these patterns.
 
-## Section Contract (HARD RULES — non-negotiable)
+## Section Contract (required)
 
 The canonical template lives at `templates/reports/schedule.template.md`. **Read it before writing the schedule** and follow it byte-for-byte for headings.
 
@@ -376,7 +376,7 @@ After the `Item / Detail` table, every per-task block MUST emit these sub-sectio
 4. `**Verification Commands**:` (followed by a fenced ` ```bash ` block)
 5. `**Rollback**:`
 
-The validator enforces order by scanning each `### N-i.` block. A missing section or an out-of-order section is a hard violation. **Never emit `#### 사용자 확인 필요 항목`** — this is a client-facing schedule (see "Audience" above).
+The validator enforces order by scanning each `### N-i.` block. A missing section or an out-of-order section is a contract violation. **Never emit `#### 사용자 확인 필요 항목`** — this is a client-facing schedule (see "Audience" above).
 
 ### MUST — controlled vocabulary (enums)
 
@@ -444,45 +444,15 @@ After writing the file and before printing the completion message in Step 7, you
    python3 validators/validate-schedule.py <output-path>
    ```
 3. If the validator exits non-zero, **fix the file and re-validate**. Do not print the completion message until the validator passes.
-4. If `validators/validate-schedule.py` is not present in the repo, fall back to a manual checklist: confirm each of the 11 mandatory headings appears in the file with the exact spelling above, the title ends with `— Work Schedule`, and the metadata `> Generated:` block is present.
+4. If `validators/validate-schedule.py` is not present in the repo, fall back to a manual checklist: confirm each of the 11 mandatory headings from `### MUST — exact ordered heading list` (above) appears in the file with that exact spelling, the title ends with `— Work Schedule`, and the metadata `> Generated:` block is present.
 
 ## Schedule Document Template
 
-The generated Markdown file MUST follow this structure exactly, mirroring `templates/reports/schedule.template.md`. Do not omit sections; if data is unavailable for a section, include the section with the placeholder `_없음_` rather than skipping it.
+[`templates/reports/schedule.template.md`](../../templates/reports/schedule.template.md) is the byte-for-byte SSOT for section ordering, heading spelling, table columns, and per-section HTML-comment guidance (Dependency Graph Shape A/B, Gantt rules, optional Glossary gate). Do not omit sections; if data is unavailable, render the section with `_없음_` rather than skipping it.
 
-### Required Top Header
+The two rules below complement the template — they encode COMPUTATION that the template scaffold cannot carry inline.
 
-```markdown
-# <Title> — Work Schedule
-
-> Generated: <YYYY-MM-DD HH:MM> | Project: <project-id> | Task Group: <task-group>
-> Source: okstra <mode> (<N> tasks included, <M> done excluded)
-
----
-```
-
-### Section: At a Glance (FIRST content section after header)
-
-This section gives the reader the entire schedule scope at a single screen.
-
-```markdown
-## At a Glance
-
-**총 <N>개 task / 예상 소요: <X.X> ~ <Y.Y> days (Effort 합산)**
-
-| # | Task ID | Title | Category | Priority | Effort | Days | taskType | Risk | Phase |
-|---|---------|-------|----------|----------|--------|------|----------|------|-------|
-| 1 | <TASK-ID> | <Title> | <category> | <P0~P3> | <S/M/L/XL> | <range> | <taskType> | <risk> | <1/2/3> |
-| ... |
-
-**Effort 분포**: S × <n> / M × <n> / L × <n> / XL × <n>
-**Risk 분포**: Very Low × <n> / Low × <n> / Medium × <n> / Med-High × <n> / High × <n>
-**Repo별 영향**: <repo1> (<n>) / <repo2> (<n>) / ...
-
----
-```
-
-Effort-to-Day mapping (used to compute the total day range):
+### Effort-to-Day mapping (At a Glance total)
 
 | Size | Day(s)   |
 |------|----------|
@@ -491,131 +461,18 @@ Effort-to-Day mapping (used to compute the total day range):
 | L    | 3 - 5    |
 | XL   | 5 - 10   |
 | XXL  | 10 -     |
-Sum the lower bounds for the lower total and the upper bounds for the upper total.
-
-### Section: Executive Summary
-
-```markdown
-## Executive Summary
-
-<Phase 분류 요약 + 진행 전략 — 2~4문장>
-
-- **Phase 1 (Critical Fixes)**: <n>개 task — <summary>
-- **Phase 2 (Enhancements)**: <n>개 task — <summary>
-- **Phase 3 (Architecture)**: <n>개 task — <summary>
-
-### Effort Sizing 기준
-
-| Size | 기준 | Day(s) |
-|------|------|--------|
-| **S** | 1-2 files, 1 repo, 테스트 수정만, DB 변경 없음 | 0.5 - 1 |
-| **M** | 3-5 files, 1 repo, 신규 테스트 포함, DB 변경 없음 | 2 - 3 |
-| **L** | 5-15 files, 2-3 repos, 순차 배포, 패키지 릴리스 포함 가능 | 3 - 5 |
-| **XL** | 15+ files, 3+ repos + infra, frontend 동시 변경, 아키텍처 전환 | 5 - 10 |
-| **XXL** | 작업 더 세분화 필요 | 10 - |
-
----
-```
-
-### Section: Task Dependency Graph
-
-This section MUST follow ONE of two exact shapes — free-form ASCII art, mermaid, PlantUML, or Graphviz are all forbidden.
-
-**Shape A — no dependency data.** Single italicized blockquote-line under the heading, literal Korean:
-
-```
-_의존 정보 없음_
-```
-
-**Shape B — adjacency-list inside a plain fence.** When dependency edges are extracted from per-task reports, emit them as a fenced block with NO language tag. Each non-empty line is one of:
-
-- An adjacency line: `<TASK-ID> -> <TASK-ID>[, <TASK-ID>]*`
-- A comment line starting with `#` (free prose, max one per group)
-- A blank line (group separator)
-
-```
-DEV-1 -> DEV-2, DEV-3
-DEV-2 -> DEV-4
-# Phase 3 fan-out
-DEV-5 -> DEV-6
-```
-
-Rules:
-- Use ASCII arrow `->` only. Unicode `→` is rejected so downstream tooling does not have to handle both.
-- Both endpoints MUST be `TASK-ID` literals (the same identifiers used in the At a Glance table). Free text is forbidden.
-- Fence MUST be plain ` ``` ` with no language tag. ` ```mermaid `, ` ```plantuml `, ` ```graphviz `, ` ```dot ` are all rejected.
-- If only one task is in scope (no dependencies), use Shape A — do NOT emit an empty fence.
-
-### Section: Phase 1 / Phase 2 / Phase 3
-
-For each phase, repeat the per-task block:
-
-````markdown
-## Phase <N>: <Name>
-
-### <N>-<i>. <TASK-ID> — <Title>
-
-| Item | Detail |
-|------|--------|
-| **Category** | <category> |
-| **Priority** | <P0~P3> |
-| **Effort** | **<S/M/L/XL>** (<scope summary>) |
-| **Status** | <workStatus + currentPhase summary> |
-| **Risk** | <risk> |
-| **Scope** | <files / repos summary> |
-| **Repo** | <repos> |
-
-**Problem**: <…>
-
-**Solution**: <…>
-
-**Work Breakdown**:
-
-| Step | File | Action | Detail |
-|------|------|--------|--------|
-| 1 | <path> | CREATE/MODIFY/VERIFY | <detail> |
-| ... |
-
-**Verification Commands**:
-```bash
-<commands>
-```
-
-**Rollback**: <…>
-
----
-````
-
-If a task entry is `[NEEDS-OKSTRA-RUN]` or `[PARSE-ERROR: <section>]`, place the marker immediately under the task heading and fill only the available fields.
-
-### Section: Execution Priority Matrix
-
-```markdown
-## Execution Priority Matrix
-
-| Priority | Task | Effort | Risk | Next Action |
-|----------|------|--------|------|-------------|
-```
-
-Each row summarizes the next concrete engineering action per task in priority order. No `Done` / `Ready?` / `Blocking Decisions` columns — schedule is a client-facing plan, not an internal todo board.
-
-### Section: Cross-Task Dependencies & Shared Concerns
-
-Free-form prose listing inter-task overlaps, shared packages, release order, etc.
-
-### Section: Risk Mitigation Strategy
 
-Enumerate phase-level risk strategies as numbered list.
+Sum the lower bounds across all in-scope tasks for the lower total, and the upper bounds for the upper total. The same table is rendered as descriptive reference under `### Effort Sizing 기준`; this copy is the source-of-truth for the At a Glance computation.
 
-### Section: Recommended Immediate Actions
+### `[NEEDS-OKSTRA-RUN]` / `[PARSE-ERROR: <section>]` placement
 
-Markdown bullet list of next concrete engineering actions, one item per line: `- <action>`. Numbered lists (`1. …`) and checkbox lists (`- [ ] …`) are both forbidden — the schedule is a client-facing plan, not an internal todo.
+When a task entry is tagged with one of these markers, place the marker immediately under the per-task heading inside the corresponding Phase section and fill only the available fields. Do NOT relocate it to a sibling section.
 
 ## Edge Cases
 
 | Case | Handling |
 |------|----------|
-| `workStatus` field absent or empty | Resolve via the okstra-status inference table; include unless the resolved value is `done` |
+| `workStatus` field absent or empty | Resolve via the `okstra-inspect status.4` inference table; include unless the resolved value is `done` |
 | Filtered task count is 0 | Emit "모든 task가 done" message; do NOT create a file |
 | `latestReportPath` missing or unreadable | Tag entry with `[NEEDS-OKSTRA-RUN]`; include manifest metadata only |
 | Report parsing fails for a specific section | Tag with `[PARSE-ERROR: <section>]`; continue with the rest |

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

@@ -17,7 +17,7 @@ machine, or when adopting okstra in a new project.
 ## When NOT to use
 
 - A task is already in flight → use [`okstra-run`](../okstra-run/SKILL.md) or
-  [`okstra-status`](../okstra-status/SKILL.md).
+  [`okstra-inspect status`](../okstra-inspect/SKILL.md).
 - Day-to-day usage in a project that already has `project.json` — skip this skill.
 
 ## Prerequisites
@@ -111,6 +111,9 @@ Each okstra run provisions a task-scoped git worktree under
 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`.
+Syncing a directory does not make it okstra memory; okstra-owned context
+and writes still stay under `<PROJECT_ROOT>/.project-docs/okstra/**`
+unless the task brief explicitly authorizes a non-okstra path.
 
 To override per-project, add a `worktreeSyncDirs` array to
 `project.json`. Empty array disables the feature; the field is
@@ -251,6 +254,30 @@ If the user chose `나중에`, tell them they can register later with one of:
   (the run can also persist that override to project/global scope on the
   spot — see the okstra-run skill).
 
+## Step 4.9 (optional): choose final report language
+
+기본은 영어. 이 step 을 skip 하면 `reportLanguage` 필드를 두지 않고
+runtime 이 `auto` 로 처리한다 — 즉 task brief 의 주 서술 언어를 따라
+간다 (한국어 brief → 한국어 report, 영어 brief → 영어 report).
+
+사용자가 명시적으로 선택하면 `okstra config set` 으로 `project.json`
+에 기록한다.
+
+AskUserQuestion (fixed options):
+- Question: `"Final report 를 어느 언어로 작성할까요?"`
+- Options:
+  1. `English (recommended)` → reportLanguage: "en"
+  2. `한국어` → reportLanguage: "ko"
+  3. `Auto (task brief 언어로 추론, 불분명하면 영어)` → reportLanguage: "auto"
+  4. `나중에` → skip (필드 미설정 → runtime 이 auto 로 처리)
+
+If the user picks 1/2/3, run:
+
+`okstra config set report-language <en|ko|auto> --scope project`
+
+전역 기본값을 두고 싶다면 README 의 "global config" 안내를 따라
+`--scope global` 로 수동 설정한다. 이 step 에서는 project 스코프만 제공한다.
+
 ## Step 5: Verify
 
 ```bash

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -70,8 +70,11 @@ Every worker prompt MUST start with the following anchor headers, in this exact
 
 1. `**Project Root:** <absolute-path>` — absolute target project root (from `{{PROJECT_ROOT}}` in the lead's prompt). Required so the worker can self-anchor without relying on inherited cwd.
 2. `**Prompt History Path:** <project-relative-path>`
-3. `**Result Path:** <project-relative-path>` — canonical destination for the worker's result file. Workers resolve it to absolute against `**Project Root:**` and use it for the post-completion existence check (see codex-worker / gemini-worker step 8c, and Lead's redispatch policy below). The path identifies a single file; do NOT deliver a directory.
+3. `**Result Path:** <project-relative-path>` — canonical destination for the worker's result file. Workers resolve it to absolute against `**Project Root:**` and use it for the post-completion existence check (see CLI wrapper agents' step 8c, and Lead's redispatch policy below). The path identifies a single file; do NOT deliver a directory.
 4. `Assigned worker prompt history path: <absolute-path>` — same as the prompt-history path but resolved against `Project Root`. Codex/Gemini wrapper subagents extract this exact line.
+5. `**Worker Preamble Path:** <absolute-path>` — points to `~/.okstra/templates/worker-prompt-preamble.md` (canonical SSOT for Required Reading + Error Reporting + Anchor / Output sections). Workers Read this file end-to-end before producing any output. This anchor replaces the ~80 lines of inlined `[Required reading]` / `[Error reporting]` boilerplate that earlier versions injected into every dispatch.
+6. `**Errors log path:** <absolute-path>` — run-level errors JSONL.
+7. `**Errors sidecar path:** <absolute-path>` — this worker's per-run sidecar JSON.
 
 The body must include: role name, task type, task key, required bundle paths, assigned model, output contract, evidence handling rules, and any relevant config/deployment expectations from `reference-expectations.md`.
 
@@ -83,120 +86,26 @@ Before dispatching any required worker, lead persists the exact worker prompt to
 
 Send byte-identical dispatch prompts to every analysis worker (Claude / Codex / Gemini), modulo the role label and the wrapper-specific path headers enumerated in the "Dispatch-prompt invariant" rule of the Role Definitions section. The prior "role-specific emphasis" guidance is retired — emphasis in the body biases each worker toward its lens and silently kills convergence (see Role Definitions for the failure mode). Specialization lives in Section 6 of the worker output, not in the dispatch prompt body.
 
-### Required reading clause (analysis workers + report-writer worker)
+### Required Reading + Error Reporting via Worker Preamble (SSOT)
 
-Inject the following clause verbatim into every analysis worker's prompt and into the report-writer worker's prompt. Workers tend to skim long input documents — especially when the carry-in clarification response is structurally similar to the file they will write into next. This clause is the single biggest lever against that failure mode; do not paraphrase it, do not move it lower in the prompt, and do not omit any input file path.
+The lead does NOT inline `[Required reading]` or `[Error reporting]` blocks into worker prompts. Both contracts live in a single canonical file at `~/.okstra/templates/worker-prompt-preamble.md` (source: `templates/worker-prompt-preamble.md`). The lead injects the path via the `**Worker Preamble Path:**` anchor header (header #5 above) and each worker Reads that file end-to-end before producing output.
 
-Replace placeholder file paths in the `[Required reading]` block with the actual project-relative paths derived from the run's `instruction-set/` and (if applicable) the carry-in clarification response.
+What the lead MUST still do per dispatch:
+- Inject the input file enumeration into the dispatch prompt body via an `## Inputs` section (or any heading the recipient agent expects), listing the actual project-relative paths derived from the run's `instruction-set/` and the carry-in clarification response if any. The preamble describes the rules; the lead provides the specific paths for THIS run.
+- Inject the absolute `**Errors log path:**` and `**Errors sidecar path:**` headers (#6 and #7 above) — workers cannot synthesize these paths.
+- Omit the preamble pointer for reverify dispatches (Phase 5.5 lightweight mode) — see [okstra-convergence](../okstra-convergence/SKILL.md) "Reverify prompt: required-reading suppression".
 
-**Audience-scoped enumeration (BLOCKING — performance optimization):**
+Audience-scoped file enumeration (BLOCKING — performance optimization):
 
-Different recipients need different files. Do NOT include `final-report-template.md` in analysis worker prompts: analysis workers produce findings (not the final report), and forcing them to read the template inflates token usage without changing finding quality.
-
-| Recipient | Files included in `[Required reading]` |
+| Recipient | Files the lead lists under `## Inputs` |
 |---|---|
 | Claude / Codex / Gemini analysis workers | task-brief, analysis-profile, analysis-material (if present), reference-expectations, clarification-response (if carry-in) |
 | Report writer worker (Phase 6) | all of the above **plus** `final-report-template.md` |
-| Reverify dispatches (Phase 5.5, lightweight mode) | **do NOT inject the `[Required reading]` clause at all** — see [okstra-convergence](../okstra-convergence/SKILL.md) "Reverify prompt: required-reading suppression". |
-
-**Asymmetry between claude-worker and codex/gemini-worker prompts (NOT a bug):**
-
-The dispatch prompt the lead constructs for `claude-worker` is intentionally shorter than for `codex-worker` / `gemini-worker`. Do NOT "fix" this by re-injecting `[Required reading]` / `[Error reporting]` / `[Output Contract]` blocks into the claude-worker prompt:
-
-- `claude-worker` is an in-process Claude subagent. The Agent SDK auto-loads `agents/claude-worker.md`, which already contains `## Required Reading Before Any Analysis`, `## Worker Output Structure`, and `## Error reporting`. Re-injecting them is redundant and wastes tokens.
-- `codex-worker` / `gemini-worker` shell out to a CLI. The CLI never sees the agent definition file — it only sees the prompt body passed via stdin. Therefore the lead MUST inject those three blocks into the dispatch prompt for those two workers.
-
-Worker definition file size (claude-worker ~106 lines vs codex/gemini ~175–179 lines) is NOT evidence of incompleteness — it reflects the in-process vs CLI-wrapper distinction.
-
-```
-[Required reading]
-You are required to read every input file listed below from the very first
-character to the very last character before you produce any analysis output.
-Skimming, partial reads, jumping to a single section, or relying on prior
-knowledge of a similar file's structure is not acceptable. Each file may
-contain decisive context that is not surfaced in its summary or first page.
-
-Required files for this run (read in this order, end-to-end, no exceptions):
-
-  1. <Project Root>/<instruction-set>/task-brief.md
-  2. <Project Root>/<instruction-set>/analysis-profile.md
-  3. <Project Root>/<instruction-set>/analysis-material.md   (only if present)
-  4. <Project Root>/<instruction-set>/reference-expectations.md
-  5. <Project Root>/<instruction-set>/clarification-response.md   (only if a carry-in was provided for this run)
-  6. <Project Root>/<instruction-set>/final-report-template.md   (REPORT WRITER ONLY — omit for analysis workers and reverify dispatches)
-
-Reading rules:
-
-  - Use a single Read tool call per file with no offset and no limit. Do not
-    page through the file with offset/limit unless the file is genuinely too
-    large for one read; if you must page, you MUST cover the entire file
-    before moving on, and you MUST state the page boundaries you used in your
-    Findings section.
-  - For the carry-in clarification response, read the conditional
-    `## 0. Clarification Response Carried In From Previous Run` section
-    (rendered only when carry-in is non-empty) and every row of
-    `## 5. Clarification Items` (`C-001`, `C-002`, ...) in full,
-    including rows whose `User input` cell is blank. The fact that you
-    will write your output into a file with a structurally similar
-    section 5 is NOT an excuse to skim — the prior `C-*` rows carry
-    context you cannot reconstruct from the new run alone.
-  - Write the Reading Confirmation block to your **audit sidecar** at
-    `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md`
-    (sibling to the main worker-results file). One short line per input
-    file confirming end-to-end reading, e.g. "Read task-brief.md
-    end-to-end (147 lines)." Do NOT include a `## 0. Reading Confirmation`
-    heading in the main worker-results file — the validator now fails
-    worker-results that contain one. If you cannot truthfully confirm a
-    file end-to-end, record a `tool-failure` in the errors sidecar
-    instead of fabricating Findings.
-  - Do not collapse multiple input files into a single mental summary before
-    reading them all individually. Each file has its own canonical role
-    (brief = the user's request, profile = the lead's rules for this phase,
-    reference-expectations = ground-truth config/deployment values,
-    clarification-response = prior run's open questions and the user's
-    answers, final-report-template = the structure your eventual writeup
-    must conform to). Conflating them loses signal.
-```
-
-### Error reporting clause (analysis workers)
+| Reverify dispatches | none — the lead provides only the items to reverify |
 
-Inject the following clause verbatim into every analysis worker's prompt
-(Claude / Codex / Gemini). All three workers' subagent definitions already
-include the same contract — the prompt clause exists as a redundant safety
-net so any worker dispatched without its custom definition still receives
-identical instructions.
-
-```
-[Error reporting]
-If any tool call you make (Bash, Read, Edit, MCP, etc.) returns a non-zero
-exit code, raises an exception, or otherwise fails its intended effect,
-append a single entry to your worker errors sidecar at:
-
-  runs/<task-type>/worker-results/<role-slug>-errors-<task-type>-<seq>.json
-
-Schema (create the file with {"schemaVersion": 1, "errors": []} if absent):
-
-  {
-    "ts": "<ISO 8601 UTC>",
-    "phase": "<current okstra phase>",
-    "errorType": "tool-failure",
-    "command": "<failed command/tool signature>",
-    "commandKind": "bash | tool:Read | tool:Edit | mcp | ...",
-    "exitCode": <int or null>,
-    "durationMs": <int or null>,
-    "message": "<one-line human summary>",
-    "stderrExcerpt": "<first ~2KB of stderr, or null>",
-    "context": { ... or null }
-  }
-
-Do NOT include source / recordedAt / agent / agentRole / model / taskKey —
-Lead will fill those in. Do NOT use errorType values other than
-"tool-failure" in the sidecar. Continue your task after recording; do not
-abort unless the failure makes the task impossible.
-```
+Asymmetry note: `claude-worker` runs in-process and the Agent SDK auto-loads its agent definition; lead's dispatch prompt body for claude-worker can therefore be shorter than for codex/gemini. The Worker Preamble pointer is still emitted for all three so the contract source is identical regardless of dispatch path.
 
-The substituted `<role-slug>` is `claude-worker`, `codex-worker`, or
-`gemini-worker` matching the receiving role.
+Send byte-identical dispatch prompts to every analysis worker (Claude / Codex / Gemini), modulo the role label and the wrapper-specific path headers. The prior "role-specific emphasis" guidance is retired — specialization lives in Section 6 of the worker output, not in the dispatch prompt body.
 
 ## Terminal Statuses
 
@@ -374,7 +283,7 @@ without proceeding — this is the contractual replacement for the previous
 empty run-level error logs in production.
 
 - `cli-failure` events are recorded by the wrapper subagent itself (Codex / Gemini), but **directly to the run-level error log** via `okstra-error-log.py append-observed --error-type cli-failure ...` — NOT via the sidecar. The sidecar is an in-process tool-failure channel only.
-- **Wrapper invocation arity.** Both `okstra-codex-exec.sh` and `okstra-gemini-exec.sh` accept four required positional arguments plus an optional fifth `<role>`: `<project-root> <model> <prompt-path> <worktree-path> [<role>]`. The fourth (worktree) argument is **mandatory for implementation phase** and optional otherwise. For codex it becomes `--add-dir <worktree>` (sandbox write access); for gemini it is appended to `--include-directories`. Omitting it during implementation causes the codex sandbox to reject every Edit/Write targeting the worktree with EPERM. Workers extract the path from the `**Worktree:**` / `EXECUTOR_WORKTREE_PATH` / `cwd for every mutating command:` line in the lead prompt. The optional fifth `<role>` is folded into both the caller (worker) pane title `<cli>-<role>-<pid>` and the sibling trace-pane title `<cli>-<role>-<pid>-trace` (e.g. `codex-worker-93421` ↔ `codex-worker-93421-trace`). `<pid>` is the wrapper's own PID and disambiguates concurrent dispatches of the same role. Always pass the literal string `worker` so the dispatch is self-describing (the wrapper defaults to `worker` if omitted).
+- **Wrapper invocation arity.** Both `okstra-codex-exec.sh` and `okstra-gemini-exec.sh` accept four required positional arguments plus an optional fifth `<role>`: `<project-root> <model> <prompt-path> <worktree-path> [<role>]`. The fourth (worktree) argument is **mandatory for implementation phase** and optional otherwise. For codex it becomes `--add-dir <worktree>` (sandbox write access); for gemini it is appended to `--include-directories`. Omitting it during implementation causes the codex sandbox to reject every Edit/Write targeting the worktree with EPERM. Workers extract the path from the `**Worktree:**` / `EXECUTOR_WORKTREE_PATH` / `cwd for every mutating command:` line in the lead prompt. The optional fifth `<role>` is folded into both the caller (worker) pane title `<cli>-<role>-<pid>` and the sibling trace-pane title `<cli>-<role>-<pid>-trace[from=<caller-pane-id>]` (e.g. `codex-worker-93421` ↔ `codex-worker-93421-trace[from=%5]`). `<pid>` is the wrapper's own PID and disambiguates concurrent dispatches of the same role; the embedded caller pane id keeps the trace ↔ worker correlation visible even when the worker pane's title is overwritten by the parent process (Claude Code's TUI emits OSC 2 title escape sequences on its own pane). Always pass the literal string `worker` so the dispatch is self-describing (the wrapper defaults to `worker` if omitted).
 - **Background dispatch + polling contract (Codex / Gemini wrappers).** Both wrapper subagents MUST dispatch `okstra-codex-exec.sh` / `okstra-gemini-exec.sh` via `Bash(run_in_background: true)` and poll with `BashOutput(bash_id)` until the shell reports `status == "completed"`, capped at 30 minutes (1800s) of wall-clock elapsed time. `BashOutput` itself is the wait primitive — call it back-to-back; do NOT insert a standalone `sleep` between polls. The Claude Code harness blocks `sleep` calls of 5 seconds or longer as a circumvention vector and explicitly forbids chaining shorter sleeps inside until-loops to work around the block. Workers that hit the contract bug must NOT self-recover with `until ...; do sleep 2; done` wrappers — that path violates the harness anti-circumvention rule, even though it superficially "works". The legacy "single foreground `Bash` with 120000ms timeout" rule, and the subsequent "60-second cadence with `sleep 60` between polls" rule, are both retired. The current rule applies in **every phase** (analysis runs typically complete in 1–2 `BashOutput` calls, so there is no regression for short jobs). Recording responsibilities:
   - Successful completion: return the wrapper's accumulated stdout from the final `BashOutput`. No log entry.
   - Non-zero `exit_code` reported by `BashOutput`: record a `cli-failure` to the run-level error log with the real `exit_code` and observed `duration-ms`.