okstra 0.8.0 → 0.10.0

package/README.kr.md

@@ -51,6 +51,8 @@ okstra/                          npm 패키지 = repo 루트
 ├── installed-agents.json        설치된 워커 에이전트 매니페스트 (uninstall 이 사용)
 ├── recent.jsonl, active.jsonl   run 인덱스
 ├── projects/                    프로젝트별 메타데이터 미러
+├── worktrees/                   `--task-type implementation` run 마다 자동 생성되는
+│                                격리 git worktree (run 종료 후 자동 삭제하지 않음)
 └── archive/                     완료된 run
 
 ~/.claude/skills/                Claude Code 가 자동 인식
@@ -134,11 +136,9 @@ Claude Code 세션 안에서 사용하는 슬래시 커맨드:
 | `/okstra-status` | phase / 상태 조회, task 의 workStatus 설정 |
 | `/okstra-history` | 과거 task 목록, 이어할 task 선택 |
 | `/okstra-schedule` | task-group 전체에 대한 작업 계획표 생성 |
-| `/okstra-time-summary` | 소요 시간 분석 (lead + worker 별) |
-| `/okstra-report-finder` | task-key 로 최종 보고서 조회 |
 | `/okstra-setup` | 프로젝트별 부트스트랩 (§3.2) |
 
-이 외에 `okstra-context-loader`, `okstra-team-contract`, `okstra-convergence`, `okstra-report-writer` 4종은 lead 가 phase 진행 도중 내부적으로 호출하는 스킬로, 사용자가 직접 부르는 일은 거의 없습니다.
+이 외에 `okstra-context-loader`, `okstra-team-contract`, `okstra-convergence`, `okstra-report-writer`, `okstra-time-summary`, `okstra-report-finder` 6종은 `user-invocable: false` 로 표시되어 슬래시 커맨드로 노출되지 않습니다. lead 또는 Claude 가 자연어 트리거(예: "이 task 얼마나 걸렸어?" → `okstra-time-summary`, "보고서 찾아줘" → `okstra-report-finder`)로 자동 호출합니다.
 
 ### 3.4 CLI 모드 (선택)
 
@@ -155,6 +155,17 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 
 새 `claude` 프로세스를 띄워 lead 역할로 동작시킵니다. 전체 인자 목록은 `okstra.sh --help` 또는 [`docs/kr/cli.md`](docs/kr/cli.md) 참조.
 
+0.7.0 / 0.8.0 에서 추가된 주요 플래그:
+
+- `--executor claude|codex|gemini` — `--task-type implementation` 에서 파일을 mutate 할 provider 를 선택합니다. 나머지 두 provider 는 같은 run 에서 strict read-only verifier 로 dispatch 됩니다 ([`docs/kr/cli.md`](docs/kr/cli.md#--executor)).
+- `--work-category bugfix|feature|refactor|ops|improvement` — `requirements-discovery` phase 를 건너뛰는 경우 작업 분류를 직접 지정합니다.
+- `--approve` — `--approved-plan` 과 함께 사용하면 CLI 호출 자체를 implementation-planning 승인 신호로 처리합니다 (제거된 `--ack-approved` alias 대체).
+
+0.8.0 이후 `main` 에 추가된 workflow 변경:
+
+- **`--task-type implementation` 격리 worktree 자동 provisioning** — prepare 단계에서 `okstra-ctl` 이 `git worktree add ~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>-<run-seq>` 를 수행해 격리된 working tree 와 브랜치 `<work-category-prefix>-<task-id-segment>-<run-seq>` (예: `feat-dev-9436-001`, `fix-dev-7311-002`) 를 만듭니다. base ref 는 prepare 시점의 `HEAD`. Executor 와 verifier 모두 이 worktree 안에서 동작하므로 caller 의 작업 디렉터리는 깨끗하게 유지되고, worktree 는 PR 작성 · rollback 검증의 권위 artefact 로 남습니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 됩니다. 수동 cleanup: `git worktree remove <path>` → `git branch -D <branch>`. 상세: [`docs/kr/architecture.md`](docs/kr/architecture.md) *Task type* 섹션, [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
+- **`release-handoff` lifecycle phase** — `final-verification` 이 `verdict=accepted` 를 반환한 직후에 실행되는 신규 phase. lead 가 Claude worker (drafter) 를 통해 commit message · PR body 후보를 만들고, `AskUserQuestion` 으로 사용자에게 (1) action (`commit only` / `commit + PR` / `skip`), (2) PR base branch (`staging` / `preprod` / `prod` / `main` / `dev` / 직접 입력), (3) message handling (`use as-is` / `edit then proceed` / `cancel`) 세 가지를 순서대로 묻습니다. 사용자가 메뉴로 선택한 git / gh 명령만 실행되고, force-push, base 브랜치 직접 push, hook bypass (`--no-verify`), release publish (`gh release`, `npm publish`, ...) 는 금지됩니다. 이 phase 에서는 소스 코드를 수정하지 않습니다. profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
+
 ### 3.5 운영 명령
 
 | 커맨드 | 용도 |

package/README.md

@@ -50,6 +50,8 @@ okstra/                          npm package = repo root
 ├── installed-agents.json        manifest of installed worker agents (used by uninstall)
 ├── recent.jsonl, active.jsonl   run index
 ├── projects/                    per-project metadata mirror
+├── worktrees/                   isolated git worktrees auto-provisioned per
+│                                `--task-type implementation` run (not auto-removed)
 └── archive/                     completed runs
 
 ~/.claude/skills/                discovered automatically by Claude Code
@@ -133,11 +135,9 @@ User-facing slash commands inside a Claude Code session:
 | `/okstra-status` | Phase / state overview, or set a task's workStatus |
 | `/okstra-history` | List past tasks, choose what to resume |
 | `/okstra-schedule` | Generate a work schedule for an entire task-group |
-| `/okstra-time-summary` | Elapsed-time breakdown (lead + per-worker) |
-| `/okstra-report-finder` | Look up a final report by task-key |
 | `/okstra-setup` | Per-project bootstrap (§3.2) |
 
-Four additional skills — `okstra-context-loader`, `okstra-team-contract`, `okstra-convergence`, `okstra-report-writer` — are invoked by the lead during phase progression; users rarely call them directly.
+Six additional skills — `okstra-context-loader`, `okstra-team-contract`, `okstra-convergence`, `okstra-report-writer`, `okstra-time-summary`, `okstra-report-finder` — are marked `user-invocable: false` and do not appear as slash commands. Claude still invokes them automatically via natural-language triggers (e.g. "이 task 얼마나 걸렸어?" routes to `okstra-time-summary`; "show me the report for X" routes to `okstra-report-finder`).
 
 ### 3.4 CLI mode (optional)
 
@@ -154,6 +154,17 @@ To kick off a task from outside a Claude Code session:
 
 Spawns a fresh `claude` process and hands it the lead role. Full argument list: `okstra.sh --help`, or the [Required arguments](README.kr.md#required-arguments) section in the Korean manual.
 
+Notable flags added in 0.7.0 / 0.8.0:
+
+- `--executor claude|codex|gemini` — pick the provider that mutates files during `--task-type implementation`. The other two providers are still dispatched as read-only verifiers (see [`docs/kr/cli.md`](docs/kr/cli.md#--executor)).
+- `--work-category bugfix|feature|refactor|ops|improvement` — classify a task when the lifecycle skips `requirements-discovery`.
+- `--approve` — combined with `--approved-plan`, treats the CLI invocation itself as the implementation-planning approval signal (replaces the removed `--ack-approved` alias).
+
+Recent workflow additions (post-0.8.0, on `main`):
+
+- **Isolated executor worktree for `--task-type implementation`** — prepare automatically runs `git worktree add ~/.okstra/worktrees/<project>/<group>/<task>-<seq>` on a fresh branch `<work-category-prefix>-<task-id-segment>-<seq>` branched from `HEAD`. Executor and verifiers operate inside that worktree so the caller's working tree stays clean, and the worktree is preserved after the run as the canonical artefact for PR authoring and rollback. Skip paths: when the caller is already inside another worktree or `project_root` is not a git repo, provisioning no-ops. Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>`. Details: [`docs/kr/architecture.md`](docs/kr/architecture.md) (*Task type* section) and [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
+- **`release-handoff` lifecycle phase** — runs after `final-verification` returns `verdict=accepted`. The lead drafts a commit message and PR body via a Claude worker, then prompts the user with `AskUserQuestion` for three choices: action (`commit only` / `commit + PR` / `skip`), PR base branch (`staging` / `preprod` / `prod` / `main` / `dev` / free-form), and message handling (`use as-is` / `edit then proceed` / `cancel`). Only user-selected mutating git/gh commands run. Force-push, base-branch direct push, hook bypass (`--no-verify`), and release publishing (`gh release`, `npm publish`, ...) are forbidden. Source code is not edited in this phase. Profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
+
 ### 3.5 Ops commands
 
 | Command | Use |

package/docs/kr/architecture.md

@@ -13,7 +13,7 @@
 핵심 기능을 한눈에 정리하면 다음과 같습니다.
 
 - **Task identity**: `<project-id>/<task-group>/<task-id>` 기반 stable task key로 task root를 생성하거나 재사용하고, manifest · index · timeline을 일관되게 갱신합니다.
-- **Task type별 profile**: `requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification` 등 표준 task type 프로파일을 로드해 instruction-set을 렌더링합니다.
+- **Task type별 profile**: `requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff` 등 표준 task type 프로파일을 로드해 instruction-set을 렌더링합니다.
 - **Run lifecycle**: 매 실행마다 per-run 디렉터리(`runs/<timestamp>/`)에 prompt snapshot, sessions/, expected-state, final report 템플릿, run manifest, timeline 이벤트를 저장합니다.
 - **Single python authority**: 모든 prepare wiring(profile/workers/model 해소, path 계산, 9개 render, central record_start)이 [`okstra_ctl.run.prepare_task_bundle()`](scripts/okstra_ctl/run.py) 한 함수에 모여 있습니다. `okstra.sh` 와 `okstra-run` skill 은 같은 함수를 호출하는 thin caller 이며, 환경 변수로 상태를 전달하지 않습니다 — task 정체성·경로·workflow 상태는 모두 디스크 권위 파일에서 매번 계산됩니다.
 - **Claude handoff (두 모드)**: (a) `okstra.sh` 가 새 `claude` 프로세스를 띄우는 전통 방식, (b) `okstra-run` skill 이 현재 claude 세션 안에서 prepare 후 lead 역할을 그대로 인계받는 in-session 모드. 둘 다 `prepare_task_bundle` 의 산출물(instruction-set 등)을 그대로 사용합니다.
@@ -125,7 +125,7 @@ okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_ta
 ### Claude assets (templates + skills)
 
 - `prompts/launch.template.md` — lead 프롬프트 템플릿.
-- `prompts/profiles/*.md` — 5종 task-type profile.
+- `prompts/profiles/*.md` — 6종 task-type profile (`requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`).
 - `templates/project-docs/task-index.template.md` · `templates/reports/final-report.template.md` · `templates/reports/settings.template.json` — 런타임 렌더 입력.
 - `<PROJECT_ROOT>/.project-docs/okstra/project.json` — 프로젝트 self-registration. okstra.sh 첫 실행 시 자동 생성/검증되며, `--project-root` 미지정 시 ancestor / `git toplevel` 로 PROJECT_ROOT 해석.
 
@@ -315,11 +315,14 @@ Claude launch prompt 본문은 항상 `prompts/launch.template.md` 템플릿에
 | `error-analysis` | 보고된 에러/사고의 증상·원인·재현 갭을 증거 기반으로 분석 | symptom/trigger 정리, root-cause 가설, reproduction gap, validation 경로 | `implementation-planning` | 금지 |
 | `implementation-planning` | 코딩 시작 전 안전한 구현 방향과 옵션을 평가 | 최소 2개 구현 옵션, 영향 파일 목록, trade-off, 단계별 실행 순서, validation/rollback, **User Approval Request** 블록 | `implementation` (사용자 승인 후) | 금지 |
 | `implementation` | 승인된 `implementation-planning` final report의 단계대로 소스 코드를 수정 | commit list, diff summary, out-of-plan edits 블록, validation/TDD evidence, rollback 검증, verifier 결과(Gemini/Codex/Claude) | `final-verification` | 허용 (승인된 plan의 파일 목록 한정, `git push`/publish/deploy/실제 migration 금지) |
-| `final-verification` | 완료된 작업의 잔존 결함·회귀 위험을 점검하고 release 판단 | acceptance verdict, residual risk, follow-up 라우팅(`error-analysis`/`implementation-planning`) | `done-or-follow-up` | 금지 (read-only 테스트만 허용) |
+| `final-verification` | 완료된 작업의 잔존 결함·회귀 위험을 점검하고 release 판단 | acceptance verdict, residual risk, follow-up 라우팅(`error-analysis`/`implementation-planning`/`release-handoff`) | `pending-release-handoff` (verdict 가 `accepted` 일 때만 `release-handoff` 로 진입; 그 외에는 `error-analysis` 또는 `implementation-planning` 으로 리라우팅) | 금지 (read-only 테스트만 허용) |
+| `release-handoff` | `accepted` 받은 변경을 사용자가 선택한 방식대로 커밋·푸시·PR 로 전달 | 사용자 메뉴 응답(H1 action / H2 PR base / H3 message handling) 기록, 실행한 git/gh 명령 로그, commit SHA 목록, PR URL | `done-or-follow-up` | 허용 — 단 **사용자가 메뉴로 선택한 mutating 명령만** 실행. `git push --force*`, base 브랜치 직접 push, `--no-verify`, `gh release`, publish/deploy 는 금지. source code 자체는 수정 금지(이전 `implementation` 의 diff 를 그대로 패키징). |
 
 공통 제약:
 
 - `implementation`을 제외한 모든 phase는 source code edit, build, migration, deployment, 그 밖의 state-mutating 명령을 금지합니다(`final-verification`은 read-only 테스트 명령만 허용). `implementation`은 승인된 plan의 파일 목록 안에서만 edit/commit이 허용되며, `git push`·publish·deploy·실제 migration·third-party write API는 여전히 금지됩니다.
+- **`implementation` 격리 worktree (BLOCKING)**: `--task-type implementation` run은 prepare 단계에서 `okstra-ctl` 이 자동으로 `git worktree` 를 생성해 executor·verifier가 모두 그 안에서 작업하도록 강제합니다. 위치는 `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>-<run-seq>` 이고, 브랜치 이름은 `<work-category-prefix>-<task-id-segment>-<run-seq>` (예: `feat-dev-9436-001`, `fix-dev-7311-002`) 입니다. base ref 는 prepare 시점의 `HEAD`. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 되고 executor 는 project_root 에서 그대로 작업합니다. worktree 는 run 종료 후 자동 삭제되지 않으며 PR 작성·rollback 검증·후속 `final-verification` 의 권위 artefact 입니다. 수동 cleanup: `git -C <project_root> worktree remove <path>` 후 `git -C <project_root> branch -D <branch>`. 자세한 동작은 `prompts/profiles/implementation.md` 의 *Executor worktree* 블록과 `agents/SKILL.md` 의 *Implementation phase: Executor binding → Executor worktree* 섹션 참고.
+- `implementation` 과 `release-handoff` 를 제외한 모든 phase 는 source code edit, build, migration, deployment, 그 밖의 state-mutating 명령을 금지합니다 (`final-verification` 은 read-only 테스트 명령만 허용). `implementation` 은 승인된 plan 의 파일 목록 안에서만 edit/commit 이 허용되며, `git push`·publish·deploy·실제 migration·third-party write API 는 여전히 금지됩니다. `release-handoff` 는 source code 자체는 수정하지 않고, 사용자가 메뉴로 선택한 commit / push / PR 명령만 실행합니다 (force push, base 브랜치 직접 push, hook bypass, release publish 는 여전히 금지).
 - 사용자가 "다음 단계 진행해" 같은 표현을 보내도, 그 발화만으로 다음 phase가 자동 시작되지 않습니다. 다음 phase는 새 `okstra.sh` 실행으로만 시작합니다.
 - **Authority & permissions assumption (HARD RULE — 모든 task-type 및 `okstra-schedule` 공통)**: 사용자(및 팀)는 예상되는 모든 작업에 대해 완전한 권한·승인 권한을 보유한다고 가정합니다. 외부 승인, 서드파티 액세스, 역할/IAM 권한, 조직적 sign-off, 법무·보안 검토, 벤더 협의, "권한 보유 여부 확인" 같은 항목을 routing 결정·missing inputs·clarification questions·risk·dependency·open questions·effort/day 추정에 포함하지 않습니다. okstra 내부 phase 핸드오프(`User Approval Request` 등)는 사용자 본인이 즉시 승인 가능한 내부 게이트이므로 영향 없으며, `implementation`의 forbidden actions(`git push`, prod deploy, shared-DB migration 등)도 권한 사유가 아닌 **안전 사유**로 계속 적용됩니다.
 - Phase별 상세 규칙은 `prompts/profiles/<task-type>.md`에 정의되어 있고, 그 본문이 그대로 `instruction-set/analysis-profile.md`로 렌더링됩니다.
@@ -722,6 +725,8 @@ scripts/okstra.sh --task-key <project-id>:<task-group>:<task-id> --workers claud
 - `[x] Approved`
 - `User Approval: APPROVED` / `User Approval: granted` / `User Approval: yes`
 
+승인 마커를 직접 편집하지 않고 CLI 호출 자체를 승인 행위로 처리하려면 `--approve` 플래그를 함께 줍니다. okstra 는 `--approved-plan` 파일의 `User Approval Request` 블록을 `- [x] Approved` 로 toggle 하고 audit 라인을 append 한 뒤 implementation phase 를 이어 실행합니다 (이전 `--ack-approved` alias 는 0.8.0 에서 제거됨). 자세한 동작은 [`docs/kr/cli.md`](cli.md#--approve) 참고.
+
 ```bash
 scripts/okstra.sh --task-type implementation --workers claude,codex,gemini --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> --approved-plan <runs/implementation-planning/.../reports/final-report.md>
 ```

package/docs/kr/cli.md

@@ -9,7 +9,7 @@
 기본 명령(첫 진입 / full args):
 
 ```bash
-scripts/okstra.sh [--render-only] [--yes] [--refresh-assets] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--gemini-model <model>] [--report-writer-model <model>] [--executor claude|codex|gemini] [--related-tasks taskA,taskB] [--clarification-response <previous-final-report>] --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>]
+scripts/okstra.sh [--render-only] [--yes] [--refresh-assets] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--gemini-model <model>] [--report-writer-model <model>] [--executor claude|codex|gemini] [--related-tasks taskA,taskB] [--work-category bugfix|feature|refactor|ops|improvement|unknown] [--clarification-response <previous-final-report>] [--approved-plan <plan-path>] [--approve] --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>]
 ```
 
 후속 phase 단축 형식(기존 task-manifest.json이 존재할 때):
@@ -288,6 +288,7 @@ fallback 기본값은 아래와 같습니다.
 - Executor 의 모델은 provider 별 worker 모델 플래그를 그대로 재사용합니다. 즉 `--executor codex` 이면 Executor 의 모델은 `--codex-model` (기본 `gpt-5.5`), `--executor gemini` 이면 `--gemini-model` (기본 `auto`) 가 됩니다.
 - Claude/Codex/Gemini 세 verifier 는 executor provider 와 관계없이 항상 dispatch 됩니다. Executor 와 같은 provider 라도 별도 CLI 세션으로 verifier 가 호출되어 context 가 분리되므로 self-review 안전장치는 유지됩니다.
 - 실제 파일 변경은 Codex/Gemini 의 경우 각 CLI 의 auto-edit 모드 (예: `codex exec --full-auto`) 를 통해 일어나며, Claude-side Edit/Write tool 을 거치지 않습니다.
+- **Executor worktree (자동 격리)**: prepare 단계에서 `okstra-ctl` 이 `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>-<run-seq>` 에 `git worktree` 를 생성하고, 브랜치 `<work-category-prefix>-<task-id-segment>-<run-seq>` 를 prepare 시점 `HEAD` 에서 분기합니다. Executor 의 Edit/Write/build/test/commit 은 모두 이 worktree 안에서 수행되며, verifier 들도 같은 worktree 를 읽어 동일한 diff 를 봅니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 되고 status 가 `skipped-in-worktree` / `skipped-not-git` 로 기록됩니다. 경로·브랜치 충돌은 `PrepareError` 로 즉시 실패시키며, run 종료 후 worktree 는 자동 삭제하지 않습니다(수동: `git worktree remove` → `git branch -D`).
 
 예:
 
@@ -300,6 +301,59 @@ scripts/okstra.sh --task-type implementation \
   --task-brief .project-docs/tasks/8852/BUG_REPORT.md
 ```
 
+### `--approved-plan`
+
+`--task-type implementation` 의 입력으로, 이전 `implementation-planning` run 의 final report 경로를 받습니다. 이 파일에는 사용자 승인 마커가 기록되어 있어야 합니다. 마커는 line-anchored, case-insensitive 로 다음 중 하나와 일치해야 합니다.
+
+- `APPROVED` (라인 시작에 단독, 또는 뒤에 공백/콜론)
+- `[x] Approved`
+- `User Approval: APPROVED` / `User Approval: granted` / `User Approval: yes`
+
+승인 마커가 없으면 run 은 `contract-violated` 로 거부됩니다. 직접 파일을 편집하는 대신 `--approve` 플래그로 CLI 호출 자체를 승인 행위로 처리할 수도 있습니다.
+
+### `--approve`
+
+`--approved-plan` 과 `--task-type implementation` 과 함께 쓰는 플래그로, **CLI 호출 자체를 plan 승인 신호로 간주**합니다. 동작:
+
+- 지정된 `--approved-plan` 파일의 최상단 `User Approval Request` 블록을 갱신합니다.
+- `- [ ] Approved` → `- [x] Approved` 로 toggle 하고, audit 라인 (`승인 일시: <ISO8601> — recorded by \`okstra --approve\``) 을 append 합니다.
+- 이미 승인 마커가 있는 파일이면 audit 라인만 보강합니다.
+- 파일에 `User Approval Request` 블록이 전혀 없으면 즉시 에러로 종료합니다 (잘못된 plan 파일을 가리키고 있을 가능성).
+
+`--approve` 는 `--task-type implementation` 이 아닌 곳에서는 의미가 없으며 에러로 종료합니다. CI/스크립트 환경 또는 한 줄로 "승인 + 다음 phase 실행" 을 함께 처리하고 싶을 때 사용합니다. (이전에 존재하던 `--ack-approved` alias 는 0.8.0 에서 제거되었습니다.)
+
+예:
+
+```bash
+scripts/okstra.sh --task-type implementation \
+  --approve \
+  --approved-plan .project-docs/.../runs/implementation-planning/.../reports/final-report.md \
+  --project-id jobs --task-group tasks --task-id 8852 \
+  --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
+
+### `--work-category`
+
+이번 task 의 작업 분류입니다. 값은 다음 중 하나입니다.
+
+- `bugfix`
+- `feature`
+- `refactor`
+- `ops`
+- `improvement`
+- `unknown` (기본값)
+
+평소에는 `requirements-discovery` phase 가 work-category 를 자동 추론하므로 명시할 필요가 없지만, 해당 phase 를 건너뛰는 lifecycle (예: 단발성 `implementation-planning` 부터 시작) 에서는 이 플래그로 분류를 직접 지정합니다. 값은 `task-manifest.json` 에 보존되어 schedule / status 스킬이 grouping 에 사용합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-type implementation-planning \
+  --work-category refactor \
+  --project-id jobs --task-group tasks --task-id 8852 \
+  --task-brief .project-docs/tasks/8852/PLAN.md
+```
+
 ### `--related-tasks`
 
 간단한 연관 task 식별자 목록을 쉼표로 전달합니다.