okstra 0.34.1 → 0.36.0

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

@@ -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

@@ -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)
 

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

@@ -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

@@ -374,7 +374,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`.

package/runtime/templates/okstra.CLAUDE.md

@@ -0,0 +1,104 @@
+# okstra — agent guidance (managed)
+
+This file is shipped by `okstra install` and surfaced into the active project
+through two channels by `okstra setup`:
+
+- **Claude Code**: `<PROJECT>/CLAUDE.md` gets an `@.project-docs/okstra/CLAUDE.md`
+  import block (per-project symlink to this template). Existing user content
+  in `CLAUDE.md` is preserved — the block lives between
+  `<!-- okstra:claude-md:begin ... -->` markers.
+- **Codex / Aider / other AGENTS.md-aware agents**: `<PROJECT>/AGENTS.md` is
+  created as a direct symlink to this template — but **only if AGENTS.md does
+  not already exist**. okstra never overwrites a hand-written AGENTS.md.
+
+It is **owned by the okstra package**: every `okstra install` overwrites
+`~/.okstra/templates/okstra.CLAUDE.md` from the version currently on disk in
+the npm package. Edits made directly to this file (or to the per-project
+`<PROJECT>/.project-docs/okstra/CLAUDE.md` / `<PROJECT>/AGENTS.md` symlinks)
+will be lost on the next install. Put project-specific overrides outside the
+managed block in `<PROJECT>/CLAUDE.md` instead (or replace `AGENTS.md` with
+your own file — okstra will respect it).
+
+## What okstra is
+
+okstra is a multi-agent cross-verification orchestrator. A Claude lead drives
+the run; codex / gemini / claude workers produce independent analyses; a
+report writer worker synthesises the final report. Day-to-day usage happens
+through slash commands inside a Claude Code session.
+
+## Slash commands
+
+| Command | When to use |
+| --- | --- |
+| `/okstra-setup` | First-time bootstrap in a new project — writes `.project-docs/okstra/project.json`, provisions `.claude/settings.local.json` and `.project-docs/okstra/CLAUDE.md`. |
+| `/okstra-brief` | Turn a requirements doc / ticket / link / conversation into the markdown task brief consumed by `okstra-run`. |
+| `/okstra-run` | Start a cross-verification task in the current session. Drives the interactive wizard. |
+| `/okstra-status` | Inspect overall okstra task status, current phase, blockers, next recommended phase. Also flips a task's workStatus (todo / in-progress / blocked / done). |
+| `/okstra-history` | List past runs, review previous results, queue a re-run. |
+| `/okstra-schedule` | Generate a consolidated work plan across multiple tasks in a task-group. |
+| `/okstra-convergence` | Iterative cross-verification between workers in Phase 5.5; classify findings by consensus level. |
+| `/okstra-report-finder` | Locate the final-report path for a given task key, or read a past report to continue work. |
+| `/okstra-report-writer` | Author / persist the final synthesis report (Phase 6–7). |
+| `/okstra-time-summary` | Per-task / per-worker elapsed time breakdown for a task-id. |
+| `/okstra-logs` | List, size, and clean up `*.log` sidecars from past worker dispatches. |
+
+Type the slash command — do not paraphrase the trigger words into prose.
+
+## Workflow boundaries
+
+- The Claude lead **does not** produce independent worker findings. It
+  dispatches workers, monitors them, and drives convergence. Analysis is the
+  workers' job.
+- Worker wrappers (`okstra-codex-exec.sh`, `okstra-gemini-exec.sh`) run from
+  `~/.okstra/bin/` and are pre-authorised via `<PROJECT>/.claude/settings.local.json`
+  (a symlink to `~/.okstra/templates/settings.local.json`). Do **not**
+  duplicate those permissions in the user's global `~/.claude/settings.json`.
+- Each okstra run provisions a task-scoped git worktree under
+  `~/.okstra/worktrees/`. Files synced from the main checkout are governed by
+  `worktreeSyncDirs` in `.project-docs/okstra/project.json` (default:
+  `.project-docs`, `.scratch`, `graphify-out`, `.claude`).
+- QA gating is configured via `qaCommands` in the same `project.json`.
+  Verifiers reject mutation-style commands (`--fix`, `--write`, `cargo update`,
+  `npm install`, etc.); declare check-only variants only.
+
+## Coding Principles (BLOCKING — agent self-checks before declaring work complete)
+
+These apply to every worker writing or editing project code (executor and verifiers alike). Enforcement is self-check: the agent runs each rule's check immediately before reporting "done"; skipping a check is itself a contract violation.
+
+1. **DRY — single reference point** — One implementation per capability. A second caller signals "extract shared logic", not "duplicate path".
+2. **KISS — simplest sufficient design** — Add abstraction layers (helper modules, strategy/factory, configuration flags, indirection) only when an existing concrete call site requires them. *Self-check: name the second caller now; if you cannot, inline.* *Example violation: extracting `formatUserName()` helper used by exactly one call site, "in case we need it elsewhere".*
+3. **YAGNI — build only for current requirements** — No speculative parameters, optional configs, "future-proof" hooks, or pre-1.0 backwards-compat shims. *Self-check: every newly introduced identifier has ≥1 current internal caller, or was explicitly user-requested.* *Example violation: adding `options?: { retries?, timeout? }` parameter when the current call passes nothing.*
+4. **Clean Code — names carry WHAT, comments explain WHY** — Identifiers must make intent obvious; if a comment would describe WHAT the code does, rename instead. Reserve comments for non-obvious WHY (hidden constraint, workaround, surprising invariant). Delete dead/commented-out code immediately — git history is the archive. *Example — WHAT (rename instead): `// increment counter` above `i++`. WHY (keep): `// retry up to 3x: upstream returns 502 during deploys`.*
+5. **Function length cap — 50 lines** — A single function/method body must stay within 50 lines, counting only effective code (exclude blank lines, comments, and pure data declarations such as large enums, lookup tables, or constant maps). Crossing the cap is an extraction signal, not a style nit. *Self-check: for any function newly added or substantially edited, count effective body lines; if over 50, split before declaring complete, or surface the violation and confirm with the user.*
+
+## Phase model (high level)
+
+```
+Phase 1  context-loader          → load brief + project context
+Phase 2  team-contract           → confirm lead + worker roster
+Phase 3  worker dispatch         → workers run independently in parallel
+Phase 4  result collection       → gather worker outputs
+Phase 5  cross-review            → workers critique each other's findings
+Phase 5.5 convergence            → classify findings, iterate until stable
+Phase 6  report-writer dispatch  → synthesise final report
+Phase 7  artifact persistence    → manifests, central index update
+```
+
+The lead skill (`okstra-run`) advances phases automatically. Use
+`/okstra-status` to inspect the current phase and `next-recommended-phase`
+hint when resuming.
+
+## Troubleshooting hints
+
+- "okstra runtime missing" / `InstallationError` — run
+  `npx okstra@latest install` (or `okstra ensure-installed`).
+- Worker dispatch refused by Claude Code permissions — verify
+  `<PROJECT>/.claude/settings.local.json` is a symlink to
+  `~/.okstra/templates/settings.local.json`; re-run `/okstra-setup` to
+  re-provision.
+- `qa-command not configured: <category>` warnings — add the missing
+  `lint` / `format` / `typecheck` / `test` entries to `qaCommands` in
+  `project.json`.
+
+For deeper documentation see the package README and `docs/` in the okstra
+source tree.