okstra 0.122.0 → 0.124.0

package/docs/for-ai/skills/okstra-schedule-gen.md

@@ -0,0 +1,320 @@
+# okstra-schedule-gen AI Manual
+
+## Source
+
+- Skill source: [`skills/okstra-schedule-gen/SKILL.md`](../../../skills/okstra-schedule-gen/SKILL.md)
+- schedule template: [`templates/reports/schedule.template.md`](../../../templates/reports/schedule.template.md)
+- schedule validator: [`validators/validate-schedule.py`](../../../validators/validate-schedule.py)
+- workStatus inference reference: [`skills/okstra-inspect/SKILL.md`](../../../skills/okstra-inspect/SKILL.md)
+
+## Purpose
+
+`okstra-schedule-gen` gathers the non-done tasks within a task-group and produces a client-facing work-schedule Markdown. It is not a skill for starting an execution task, and it is not a single-task analysis.
+
+Output location:
+
+```text
+<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/<task-group-segment>-plan-<YYYY-MM-DD_HH-MM-SS>.md
+```
+
+## When to Use
+
+Use it when:
+
+- The user requests a "schedule", "work plan", or work-schedule table for an entire task-group.
+- `.okstra/discovery/task-catalog.json` contains that task-group and it has at least one task that is not `done`.
+
+Do not use it when:
+
+- Single-task status/analysis: `okstra-inspect status`
+- Actual phase execution: `okstra-run`
+- An already-completed task-group: do not create a file; state that all tasks are done.
+
+## Preflight
+
+A single Bash call:
+
+```bash
+okstra preflight --runtime claude-code --json
+```
+
+If there is no runtime or project setup, point the user to `/okstra-setup` and stop.
+
+## Resolving the task-group
+
+1. Read `.okstra/discovery/task-catalog.json`.
+2. Lowercase the user-supplied task-group and strip characters outside `[a-z0-9]`.
+3. Apply the same transform to each catalog entry's `taskGroupPathSegment` and compare.
+4. Do not fall back to the raw `taskGroup`.
+5. Read each matched task's `task-manifest.json` directly. The catalog may be stale; the manifest is authoritative.
+
+On zero matches, output `That task-group could not be found.` and stop.
+
+## workStatus filter
+
+Check the workStatus in each manifest. When it is missing or empty, apply `okstra-inspect`'s `status.4` inference table.
+
+Exclude:
+
+- explicit `done`
+- inferred `done`
+
+Include:
+
+- `todo`
+- `in-progress`
+- `blocked`
+- `phase-done`
+- other non-done inferred/display states
+
+If 0 remain after filtering, do not create a schedule file; output `All tasks in this task-group are done. There is no schedule to generate.`
+
+## per-task data extraction
+
+Read from the manifest:
+
+- `taskId`, `taskGroup`, `taskKey`
+- `workCategory`
+- `workflow.currentPhase`
+- `workflow.currentPhaseState`
+- `taskType`
+- `workStatus`
+- `latestReportPath`
+
+Parse from the report:
+
+- Title / Problem statement
+- Solution / Architecture
+- Work Breakdown
+- Verification Commands
+- Rollback strategy
+- Effort, Risk, Priority, Scope, Repos
+
+If there is no report or the manifest pointer is stale, fall back:
+
+1. From `taskRootPath`, find the newest-mtime file under `runs/<taskType>/reports/final-report-*.md`.
+2. If none, also look at `runs/*/reports/final-report-*.md`.
+3. If found, parse it and put a fallback note in the schedule task block.
+4. If still nothing, mark it `[NEEDS-OKSTRA-RUN]` and use only the manifest metadata.
+
+Mark a specific section's parse failure as `[PARSE-ERROR: <section>]` and continue.
+
+## client-facing audience rule
+
+The schedule is a client-facing work plan. Do not surface the internal report's approval, blocking decisions, or items requiring user confirmation in the schedule.
+
+Remove from the output:
+
+- permission/authority confirmation steps
+- approval waiting buffer
+- stakeholder coordination
+- legal/organizational sign-off
+- `Consolidated User Decision Checklist`
+- `#### Items requiring user confirmation`
+- `Done`, `Ready?`, `Blocking Decisions` column
+- checkbox list/cell
+
+effort and Gantt reflect engineering duration only.
+
+## phase classification
+
+Default mapping:
+
+| workCategory | phase |
+|---|---|
+| `bugfix` | Phase 1 when High/Med-High risk, otherwise Phase 2 |
+| `feature` | Phase 2 |
+| `improvement` | Phase 2 |
+| `refactor` | Phase 3 |
+| `ops` | Phase 3 |
+| `docs` / `doc` | Phase 2 |
+| `unknown` or undefined | Phase 2, add a rationale note |
+
+priority override:
+
+- `P0`: Phase 1
+- `P1`, `P2`: Phase 2
+- `P3`: Phase 3
+
+When ambiguous, place it in the closest phase and write the rationale at the top of the phase section. This rationale is a current validator gap, so the document owns it.
+
+## section contract
+
+Follow the template's heading order and spelling. `validate-schedule.py` checks section order, title suffix, metadata, field labels, enum, Gantt axis, and more.
+
+top-level contract sections:
+
+1. `## At a Glance`
+2. `## Executive Summary` (includes the mandatory subsection `### Effort Sizing Criteria` — checked by `validate-schedule.py`)
+3. `## Task Dependency Graph`
+4. `## Phase 1: Critical Fixes`
+5. `## Phase 2: Enhancements`
+6. `## Phase 3: Architecture`
+7. `## Execution Priority Matrix`
+8. `## Cross-Task Dependencies & Shared Concerns`
+9. `## Risk Mitigation Strategy`
+10. `## Recommended Immediate Actions`
+
+optional sections:
+
+- `## Gantt Chart`: between `Task Dependency Graph` and `Phase 1`.
+- `## Glossary`: last section. Use only when opaque codes remain in the body.
+
+Keep the heading even when a phase has no task, and write `_none_`.
+
+## top header
+
+Shape:
+
+```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)
+```
+
+The validator checks the title suffix `— Work Schedule`. For `<project-id>`, prefer `task-catalog.json`'s top-level `projectId`, and if absent use the first matched manifest's `projectId`. Do not invent a value.
+
+## At a Glance
+
+This totals line must be present exactly.
+
+```markdown
+**<N> tasks total / estimated effort: <X.X> ~ <Y.Y> days (Effort sum)**
+```
+
+The Effort-to-day mapping's SSOT is the template's `### Effort Sizing Criteria` table. Build the total day range by summing the lower/upper bounds.
+
+enum values:
+
+| Field | value |
+|---|---|
+| Effort | `S`, `M`, `L`, `XL`, `XXL` |
+| Priority | `P0`, `P1`, `P2`, `P3` |
+| Risk | `Very Low`, `Low`, `Medium`, `Med-High`, `High` |
+| Phase | `1`, `2`, `3` |
+
+`Med-High` is canonical.
+
+## per-task block
+
+Every task block has a `| Item | Detail |` table. field row order:
+
+1. `**Category**`
+2. `**Priority**`
+3. `**Effort**`
+4. `**Status**`
+5. `**Risk**`
+6. `**Scope**`
+7. `**Repo**`
+
+Then the subsection order:
+
+1. `**Problem**:`
+2. `**Solution**:`
+3. `**Work Breakdown**:` — followed by a `| Step | File | Action | Detail |` table
+4. `**Verification Commands**:` — followed by a ` ```bash ` fenced block
+5. `**Rollback**:`
+
+For a `[NEEDS-OKSTRA-RUN]` or `[PARSE-ERROR: <section>]` task, fill only the available fields but place the marker right below the task heading.
+
+## Task Dependency Graph
+
+When there is no dependency, literal:
+
+```markdown
+_none_
+```
+
+When dependencies exist, use a plain fenced block. Do not attach a language tag.
+
+````
+```
+DEV-1 -> DEV-2, DEV-3
+DEV-2 -> DEV-4
+```
+````
+
+Use only the ASCII arrow `->`.
+
+## Gantt Chart
+
+**directive override (highest priority):** before applying the heuristic below, first check the directive source's `## Directive` section. Resolution order (first hit): (1) the `--directive-file <abs-path>` argument, (2) `<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/instruction-set/analysis-material.md`, (3) if none, the heuristic as-is (normal path — no warning·stop). When the directive instructs Gantt render/skip, it overrides the heuristic·skip rules, and leave one line in that section: `> _Per Directive directive: <verbatim short excerpt>._`. When the directive supplies day allocation·phase weight·sub-task decomposition, reflect it verbatim in bar length.
+
+By default, render. If there is any day signal, produce a chart even as a rough estimate.
+
+Render-condition examples:
+
+- 2+ tasks have effort sizing.
+- Even 1 task has an effort range.
+- The source report has Part/Phase/Step decomposition.
+- Total effort is 3 days or more.
+
+Skip only when every task is XXL with no decomposition, or when all tasks lack both effort and decomposition. On skip, place the following blockquote at the `Gantt Chart` position.
+
+```markdown
+> _Gantt Chart skipped: <concrete reason referencing the actual data>._
+```
+
+The Gantt is plain fenced ASCII. Do not use Mermaid, PlantUML, Graphviz, or a date axis.
+
+````
+```
+Day:            1    5    10   15   20
+                |    |    |    |    |
+Phase 1
+  DEV-1 (M)          ██████          ! crit
+Phase 2
+  DEV-2 (L)                ██████░░  est
+```
+````
+
+The axis uses relative day count only. Do not put in a calendar date, weekday, or "today + N".
+
+## handling opaque code
+
+Do not surface internal report codes (`FC-5`, `UC-3`, `M2`, etc.) as-is.
+
+Option A: inline replacement with a short description.
+
+Option B: when many codes recur, resolve every code in a final `## Glossary`. The glossary table header is exactly `| Code | Description |` (English literal — checked by the validator). Milestone codes (`M1`, `M2` …) also fail the validator when left unresolved in the glossary, just like `FC-N`.
+
+Do not put decision-item letter codes (`A1`, `B2`, `C3`, `D4`) in the schedule.
+
+## validation
+
+After writing, re-read it and run the validator before the completion message.
+
+```bash
+python3 ~/.okstra/lib/validators/validate-schedule.py <output-path>
+```
+
+If the installed validator is absent, use the repo validator.
+
+```bash
+python3 validators/validate-schedule.py <output-path>
+```
+
+On failure, fix the file and re-validate. Fall back to a manual checklist only when there is no validator.
+
+## completion message
+
+```text
+Schedule generated: <relative-path>
+- Included tasks: N
+- Excluded (done) tasks: M
+- Estimated effort: X.X ~ Y.Y days (Effort sum)
+- Mode: lightweight
+```
+
+## Forbidden patterns
+
+- Translating a heading into Korean/French/etc.
+- Adding `## Cumulative Timeline`.
+- Adding an extra top-level section such as `## Effort-to-Day mapping`.
+- Rendering the Gantt as mermaid.
+- Putting a calendar date on the Gantt axis.
+- Creating a checkbox, Done, Ready, or Blocking Decisions column.
+- Surfacing internal approval/blocker/user-decision items in the client schedule.
+- Excluding a task because it has no report. Include it as `[NEEDS-OKSTRA-RUN]`.
+- Overwriting an existing file on a timestamp collision. Append a `-2`, `-3` suffix.

package/docs/for-ai/skills/okstra-setup.md

@@ -1,52 +1,52 @@
 # okstra-setup AI Manual
 
-## 원천
+## Source
 
-- 스킬 원문: [`skills/okstra-setup/SKILL.md`](../../../skills/okstra-setup/SKILL.md)
+- Skill source: [`skills/okstra-setup/SKILL.md`](../../../skills/okstra-setup/SKILL.md)
 - CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
-- project 등록 구현: `src/commands/lifecycle/setup.mjs`
-- install/ensure-installed 구현: `src/commands/lifecycle/install.mjs`
+- project registration impl: `src/commands/lifecycle/setup.mjs`
+- install/ensure-installed impl: `src/commands/lifecycle/install.mjs`
 
-## 목적
+## Purpose
 
-`okstra-setup`은 두 가지를 처리한다.
+`okstra-setup` handles two things.
 
-1. 머신 단위 runtime 설치: `~/.okstra/`, `~/.claude/skills/`, `~/.claude/agents/`
-2. 프로젝트 단위 등록: `<PROJECT_ROOT>/.okstra/project.json`
+1. Machine-level runtime install: `~/.okstra/`, `~/.claude/skills/`, `~/.claude/agents/`
+2. Project-level registration: `<PROJECT_ROOT>/.okstra/project.json`
 
-일상적인 task 실행 스킬이 아니다. task가 이미 준비된 상태면 `okstra-run` 또는 `okstra-inspect`로 라우팅한다.
+It is not a day-to-day task-running skill. If a task is already prepared, route to `okstra-run` or `okstra-inspect`.
 
-## 사용 조건
+## When to use
 
-사용한다:
+Use it when:
 
-- 사용자가 "okstra setup", "setup okstra", "initialize okstra", "okstra init", "처음 설정"을 요청한다.
-- `~/.okstra/version`이 없거나 오래된 것으로 보인다.
-- 현재 프로젝트에 `.okstra/project.json`이 없다.
+- The user asks for "okstra setup", "setup okstra", "initialize okstra", "okstra init", "first time setup".
+- `~/.okstra/version` is missing or looks stale.
+- The current project has no `.okstra/project.json`.
 
-사용하지 않는다:
+Do not use it when:
 
-- task run을 시작하려는 경우. 이때는 `okstra-run`.
-- status/history/report를 보려는 경우. 이때는 `okstra-inspect`.
-- 이미 `.okstra/project.json`이 있고 day-to-day 사용만 필요한 경우.
+- The user wants to start a task run. Use `okstra-run` instead.
+- The user wants to view status/history/report. Use `okstra-inspect` instead.
+- `.okstra/project.json` already exists and only day-to-day usage is needed.
 
-## 실행 전 확인
+## Pre-run checks
 
-사용자에게 Node 18+, Python 3.10+가 필요하다고 알린다. 현재 working directory가 okstra 메타데이터를 둘 프로젝트 안인지 불명확하면, 프로젝트 루트를 먼저 확인한다.
+Tell the user that Node 18+ and Python 3.10+ are required. If it is unclear whether the current working directory is inside the project that will host the okstra metadata, confirm the project root first.
 
-설치 명령:
+Install command:
 
 ```bash
 npx -y okstra@latest install --runtime claude-code
 ```
 
-이 명령은 idempotent로 취급한다. 이미 설치되어 있어도 다시 실행해 runtime, skill, agent payload를 현재 package 버전과 맞춘다(agent payload = `~/.claude/agents/<worker>.md` worker 정의 + `~/.okstra/installed-agents.json` manifest). 실패하면 stderr를 그대로 사용자에게 보여준다. legacy `okstra-install.sh`로 우회하지 않는다.
+Treat this command as idempotent. Even if already installed, re-run it to align the runtime, skill, and agent payload with the current package version (agent payload = the `~/.claude/agents/<worker>.md` worker definitions + the `~/.okstra/installed-agents.json` manifest). If it fails, show the stderr to the user verbatim. Do not fall back to the legacy `okstra-install.sh`.
 
-## 명령 호출 규칙
+## Command invocation rule
 
-`okstra install` 이후에는 후속 명령이 모두 `okstra` literal token으로 시작해야 한다.
+After `okstra install`, every subsequent command must begin with the literal `okstra` token.
 
-허용되는 형태:
+Allowed forms:
 
 ```bash
 okstra check-project --json
@@ -54,87 +54,86 @@ okstra setup --yes --project-root /abs/project --project-id my-project
 okstra doctor --runtime claude-code
 ```
 
-피해야 하는 형태:
+Forms to avoid:
 
 - `export PYTHONPATH=...`
 - `eval "$(okstra paths --shell)"`
-- `$PROJECT_ROOT` 같은 shell 변수
+- shell variables like `$PROJECT_ROOT`
 - `$(...)` command substitution
-- `if`, `&&`, `||`로 감싼 okstra 호출
+- okstra calls wrapped in `if`, `&&`, `||`
 
-`okstra <subcmd>`가 자체적으로 Python path를 부트스트랩하므로 `okstra paths --shell`은 이 스킬에서 쓰지 않는다. 경로가 필요하면 `okstra paths --json`을 별도 호출로 실행하고 JSON 값을 읽는다.
+Because `okstra <subcmd>` bootstraps its own Python path, do not use `okstra paths --shell` in this skill. If you need a path, run `okstra paths --json` as a separate call and read the JSON value.
 
-## 프로젝트 루트 해석
+## Project root resolution
 
-먼저 실행:
+Run first:
 
 ```bash
 okstra check-project --json
 ```
 
-결과 처리:
+Handle the result:
 
-- `ok: true`: 이미 등록된 프로젝트다. `projectRoot`, `projectJsonPath`, `projectId`를 사용자에게 보여주고 유지 여부를 확인한다.
-- `ok: false`, `stage: "resolve"`: 사용자에게 절대 project root를 받아 `okstra check-project --cwd /abs/path --json`을 다시 실행한다.
-- `ok: false`, `stage: "project_json_missing"`: 정상 생성 경로로 진행한다.
-- 그 외 실패 stage: JSON의 `reason`을 그대로 보여주고, 원문이 지시하는 recovery를 따른다.
+- `ok: true`: already a registered project. Show `projectRoot`, `projectJsonPath`, `projectId` to the user and confirm whether to keep it.
+- `ok: false`, `stage: "resolve"`: get an absolute project root from the user and re-run `okstra check-project --cwd /abs/path --json`.
+- `ok: false`, `stage: "project_json_missing"`: proceed with the normal create path.
+- any other failure stage: show the JSON `reason` verbatim and follow the recovery the source names.
 
-## project.json 생성 또는 유지
+## Create or keep project.json
 
-`<PROJECT_ROOT>/.okstra/project.json`이 있으면 `projectId`와 `projectRoot`를 보여주고 유지/덮어쓰기 여부를 확인한다. 기본은 유지다. 기존 `projectId`를 바꾸려면 파일 삭제가 필요하므로 자동으로 덮어쓰지 않는다.
+If `<PROJECT_ROOT>/.okstra/project.json` exists, show `projectId` and `projectRoot` and confirm whether to keep or overwrite. The default is keep. Changing the existing `projectId` requires deleting the file, so do not overwrite automatically.
 
-파일이 없으면 project id를 물어본다. 답변은 비어 있지 않고 alphanumeric 문자를 하나 이상 포함해야 한다. 빈 값으로 `okstra setup --yes`를 호출하면 실패하므로 다시 묻는다.
+If the file does not exist, ask for a project id. The answer must be non-empty and contain at least one alphanumeric character. Calling `okstra setup --yes` with an empty value fails, so re-ask.
 
-생성 명령:
+Create command:
 
 ```bash
 okstra setup --yes --project-root /abs/project --project-id my-project
 ```
 
-## 선택 설정
+## Optional configuration
 
-원문상 Step 3.5 는 사용자가 명시적으로 원할 때만 수행하는 선택 설정이다 — 상세 절차는 스킬 디렉터리의 `references/project-config.md` 를 읽는다. 기본값으로 충분하면 건너뛰고 doctor로 간다.
+Per the source, Step 3.5 is optional configuration performed only when the user explicitly wants it — read `references/project-config.md` in the skill directory for the detailed procedure. If the defaults are enough, skip it and go to doctor.
 
-선택 설정:
+Optional settings:
 
-- `worktreeSyncDirs`: task worktree에 symlink할 프로젝트 상대 디렉터리 목록. 기본은 `.project-docs`, `.scratch`, `graphify-out`, `.claude`.
-- `qaCommands`: implementation verifier가 실행할 check-only lint/format/typecheck/test 명령.
-- `qaEnv`: Tier 3 conformance script가 사용할 replica/test DB, local app URL, env file, surface patterns.
+- `worktreeSyncDirs`: a list of project-relative directories to symlink into the task worktree. The default is `.project-docs`, `.scratch`, `graphify-out`, `.claude`.
+- `qaCommands`: check-only lint/format/typecheck/test commands the implementation verifier runs.
+- `qaEnv`: the replica/test DB, local app URL, env file, and surface patterns the Tier 3 conformance script uses.
 - PR body template: `okstra config set pr-template-path "<path>" --scope project|global`
 - final report language: `okstra config set report-language <en|ko|auto> --scope project`
 
-`qaCommands.cmd`는 mutation을 암시하는 token을 담으면 verifier가 거부한다. deny-list의 실제 권위는 `scripts/okstra_ctl/qa_commands.py`다.
+If `qaCommands.cmd` contains a token implying mutation, the verifier refuses it. The actual authority for the deny-list is `scripts/okstra_ctl/qa_commands.py`.
 
-## 자동 Claude 설정 symlink
+## Automatic Claude settings symlink
 
-`okstra setup`은 `<PROJECT_ROOT>/.claude/settings.local.json`을 `~/.okstra/templates/settings.local.json` symlink로 provision한다. 기존 regular file이 있으면 `.bak.<timestamp>`로 백업한 뒤 symlink를 둔다. 실패 메시지가 나오면 사용자가 기존 project-specific rule을 수동 병합해야 한다.
+`okstra setup` provisions `<PROJECT_ROOT>/.claude/settings.local.json` as a symlink to `~/.okstra/templates/settings.local.json`. If an existing regular file is present, it backs it up as `.bak.<timestamp>` and then places the symlink. If a failure message appears, the user must manually merge the existing project-specific rules.
 
-## 검증
+## Verify
 
-마지막에 실행:
+Run last:
 
 ```bash
 okstra doctor --runtime claude-code
 ```
 
-모든 check가 OK면 setup 완료로 보고한다. 실패가 있으면 출력 내용을 그대로 보여주고, 재설치/스킵 여부는 사용자가 결정하게 한다.
+If every check is OK, report setup complete. If any check fails, show the output verbatim and let the user decide whether to reinstall or skip.
 
-## 완료 메시지
+## Completion message
 
-짧게 다음 정보를 포함한다.
+Keep it short and include the following.
 
-- runtime 위치: `~/.okstra` (설치 요약의 `version stamp: x.y.z` 줄을 함께 보여준다)
+- runtime location: `~/.okstra` (also show the `version stamp: x.y.z` line from the install summary)
 - project metadata: `<PROJECT_ROOT>/.okstra/project.json`
 - `projectId`
-- 다음 단계: `/okstra-run`
+- next step: `/okstra-run`
 
-## 흔한 실패 처리
+## Common failure handling
 
-| 증상 | 처리 |
+| Symptom | Handling |
 |---|---|
-| `command not found: npx` | Node 18+ 설치 안내 |
-| `--project-id is required` | project id를 다시 물어보고 non-empty 값으로 재실행 |
-| `projectId mismatch` | 어떤 id가 canonical인지 사용자에게 확인. 자동 삭제하지 않음 |
-| `.okstra/` 쓰기 EACCES | ownership/writability 문제를 설명 |
-| `.claude/settings.local.json` symlink warning | 백업 파일과 symlink 상태를 사용자에게 보여주고 수동 병합 안내 |
-
+| `command not found: npx` | Point to installing Node 18+ |
+| `--project-id is required` | Re-ask for the project id and re-run with a non-empty value |
+| `projectId mismatch` | Confirm with the user which id is canonical. Do not delete automatically |
+| `.okstra/` write EACCES | Explain the ownership/writability problem |
+| `.claude/settings.local.json` symlink warning | Show the backup file and symlink state to the user and guide a manual merge |

package/docs/for-ai/skills/okstra-user-response.md

@@ -0,0 +1,48 @@
+# okstra-user-response AI Manual
+
+## Sources
+
+- Skill source: [`skills/okstra-user-response/SKILL.md`](../../../skills/okstra-user-response/SKILL.md)
+- Response core (CLI): [`scripts/okstra_ctl/user_response.py`](../../../scripts/okstra_ctl/user_response.py)
+- Node wrapper: [`src/commands/inspect/user-response.mjs`](../../../src/commands/inspect/user-response.mjs)
+
+## Purpose
+
+`okstra-user-response` answers the **unresolved clarification questions** an okstra run left behind (the open `C-*` rows under the final report's `## 1. Clarification Items`) **in-session**, and records those answers as a `runs/<type>/user-responses/` sidecar. The next `/okstra-run` auto-attaches this sidecar via `--clarification-response`.
+
+**Core principle — the skill never picks an answer for the user.** It only *presents* recommendations and alternatives; every `value` is the user's verbatim input. It does not call `write` until the user has explicitly confirmed (`confirmed`).
+
+Distinguish it from starting a run (`okstra-run`), inspecting a finished task (`okstra-inspect`), and generating a brief (`okstra-brief-gen`).
+
+## Sub-commands
+
+| Sub-command | What it does |
+|---|---|
+| `list` | List tasks that still have approval-open clarification (newest report first) |
+| `show` | Expand one report's open `C-*` rows (statement + recommended + alternatives + contextRefs) |
+| `write` | Record the collected answers (+ optional approval) as a `user-responses/` sidecar |
+
+## Preflight
+
+A single Bash call with the literal `okstra` token (not wrapped):
+
+```bash
+okstra preflight --runtime claude-code --json
+```
+
+`ok:true` → carry `projectRoot` and `projectId` as literals. `ok:false` → point to `/okstra-setup` and stop (retry a specific directory with `--cwd <dir>` — a leading `cd` breaks the permission match). Then resolve home once: `okstra paths --field home` → paste it literally into `--home`.
+
+## Flow
+
+1. **list**: `okstra user-response list --home <home> --project <projectId> --limit 3` → an array of `{taskKey, taskType, seq, reportPath, reportMtime, openApprovalCount, unreadable}`. If the array is empty, stop with "no open clarification". A 3-option picker (top recommendations + the final option always "Enter directly" for pasting a `reportPath`/`task-key` directly). `unreadable:true` is a §1 format drift — flag it with `⚠` and do not proceed (do not fabricate rows).
+2. **show**: `okstra user-response show --report <reportPath>` → `rows[]` with `resolvedRefs` (the `definition` of internal tokens such as `RB-002`/`§4.7`). **Do not paste the raw `statement` as the question.** For each open row present: (a) a **self-contained question** with internal tokens expanded inline first, (b) `recommended` (only a recommendation) in plain language, (c) `alternatives[]`, (d) the raw `id`+`statement` as a secondary traceability aid. If `definition` is `null`, resolve the report `§`/`path:line` yourself **using Read**.
+3. **decision (4 branches)**: the user picks one per item — Answer (accept the recommendation / own answer, verbatim), Ask-to-explain (explain only and hand the decision back to the user), Free-form (narrative verbatim), Hold+reframe (`disposition:"reframe"`, does not satisfy the approval gate). Each item's JSON: `{id, kind, value, rationale?, disposition}`.
+4. **echo → confirmed gate**: before `write`, echo the whole collection (each `id`·`disposition`·`value`·`rationale`·approval) as-is and get explicit confirmation. Never `write` before `confirmed`. On any change, re-echo and re-confirm.
+5. **approval (optional)**: only when the approval-blocking items are **all filled with an answer** and the user explicitly approved, `--approval '{"approved":true,"implementationOption":"<selected option>"}'`. If any item is unfilled/reframe, do not approve and say the gate is still open.
+6. **write**: `okstra user-response write --report <reportPath> --answers '<json>' [--approval '<json>'] --task-key <taskKey>` → report the returned `{sidecar:<path>}`. (When a same-named sidecar exists, the same `id` is overwritten with the new value and merged.)
+
+## Output Rules
+
+- Concise, in the language the user is using.
+- Give path guidance host-relative (`~/.okstra/...` or relative to `projectRoot`). Use repo paths only when pointing at a code source.
+- **Never hand-edit a rendered report** (`runs/*/reports/*.md` / `*.data.json`). Sidecar recording goes only through the `okstra user-response write` CLI.

package/docs/performance-improvement-plan-v2.md

@@ -226,13 +226,13 @@ Goals:
 
 Cautions:
 
-- Before extracting `agents/workers/_common.md`, confirm that install/packaging paths and skill/agent loaders support includes.
+- Before extracting shared worker text into `agents/workers/_cli-wrapper-template.md`, confirm that install/packaging paths and skill/agent loaders support includes.
 - Merely moving text into a separate file can increase cost if the runtime does not inline it and the worker must read another file.
 
 Change targets:
 
-- `agents/workers/codex-worker.md`
-- `agents/workers/antigravity-worker.md`
+- `agents/workers/codex-worker.params.json`
+- `agents/workers/antigravity-worker.params.json`
 - `prompts/lead/team-contract.md`
 - Install/build packaging
 
@@ -253,7 +253,7 @@ Change targets:
 - `prompts/profiles/requirements-discovery.md`
 - `scripts/okstra_ctl/workflow.py`
 - Next-phase selection UI in `skills/okstra-run/SKILL.md`
-- `skills/okstra-status/SKILL.md`
+- `skills/okstra-inspect/SKILL.md` (the former `okstra-status` skill folded into `okstra-inspect`)
 - Validator expectations
 
 Caution: