okstra 0.4.0 → 0.6.0

package/docs/kr/cli.md

@@ -0,0 +1,400 @@
+# okstra — CLI 인자 / 옵션 매뉴얼 (한국어)
+
+> 이 문서는 [README.kr.md](../../README.kr.md) 의 보충 문서입니다. 내부 아키텍처와 storage / workflow 계약은 [architecture.md](architecture.md) 를 참고하세요.
+
+---
+
+## Command forms
+
+기본 명령(첫 진입 / 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>] [--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>]
+```
+
+후속 phase 단축 형식(기존 task-manifest.json이 존재할 때):
+
+```bash
+scripts/okstra.sh --task-key <project-id>:<task-group>:<task-id> [--task-type <task-type>]
+```
+
+Clarification 답변 즉시 재실행:
+
+```bash
+scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>
+```
+
+interactive terminal에서 실행하면 다음 규칙이 추가로 적용됩니다.
+
+- 필수 인자가 비어 있으면 stdin으로 직접 입력을 받습니다.
+- 입력이 모두 준비되면 실행 전 요약을 보여줍니다.
+- `y` 또는 `yes`를 입력했을 때만 실제 생성 또는 실행 단계로 진행합니다.
+- interactive가 아닌 실행에서는 누락 인자를 prompt하지 않고 에러로 종료합니다.
+- `--yes`를 사용하면 prompt와 confirmation을 모두 건너뛰지만, 이때는 모든 필수 인자가 반드시 이미 채워져 있어야 합니다.
+- 우선순위는 `명시적 CLI 인자 > interactive prompt 또는 non-interactive 에러`입니다.
+
+## Required arguments
+
+### `--project-id`
+
+전역에서 고유해야 하는 프로젝트 ID입니다. 첫 실행 시 `<PROJECT_ROOT>/.project-docs/okstra/project.json` 에 자기 등록(self-registration)되며, 동일 PROJECT_ROOT 에서 재실행할 때 인자값과 저장된 `projectId` 가 다르면 즉시 에러로 종료합니다.
+
+예:
+
+- `fontradar-v2-api`
+- `jobs`
+
+### `--task-group`
+
+관련 task를 묶는 논리 그룹입니다.
+
+예:
+
+- `feature-8858`
+- `bugfix-auth`
+- `tasks`
+
+### `--task-id`
+
+같은 그룹 안에서 안정적으로 재사용할 task 식별자입니다.
+
+예:
+
+- `email-recipient-loss`
+- `8852`
+
+### `--task-type`
+
+이번 run의 목적과 profile 선택, run directory 세그먼트, lifecycle phase 라우팅을 결정하는 단일 입력값입니다.
+표준 값과 phase별 책임은 위 [Task type](#task-type) 섹션을 참고합니다.
+
+### `--task-brief`
+
+분석의 기준이 되는 task brief 문서 경로입니다.
+상대 경로는 대상 프로젝트 루트를 기준으로 해석됩니다.
+
+예:
+
+- `.project-docs/linear/feature/8858/okstra-task-brief.md`
+- `.project-docs/tasks/8852/BUG_REPORT.md`
+
+### `--yes`
+
+interactive prompt와 confirmation을 생략합니다.
+
+대신 아래 조건이 강제됩니다.
+
+- `project-id`
+- `task-group`
+- `task-id`
+- `task-type`
+- `brief-path`
+
+즉, 필수 인자가 하나라도 비어 있으면 prompt하지 않고 즉시 종료합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --yes --render-only --task-type error-analysis --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
+
+## Optional arguments and options
+
+### `--task-key`
+
+기존 task에 대한 후속 phase를 시작할 때 `--project-id`/`--task-group`/`--task-id`를 한 번에 전달하는 단축 형식입니다.
+
+- 입력 형식: `<project-id>:<task-group>:<task-id>`
+- 동작:
+  - 세 ID로 split하여 `PROJECT_ID`/`TASK_GROUP`/`TASK_ID`에 채웁니다.
+  - 명시적으로 같은 값들이 함께 들어오면 일치할 때만 허용하고, 충돌하면 즉시 에러로 종료합니다.
+  - 해당 task의 `task-manifest.json`이 존재하면 누락된 `--task-brief`를 manifest의 `taskBriefPath` 로, 누락된 `--task-type`을 `workflow.nextRecommendedPhase` 로 자동 채웁니다.
+  - manifest가 없으면(첫 진입) 기존 누락-인자 검증이 그대로 동작합니다(=full args 강제).
+- 명시적으로 전달된 인자가 항상 manifest 값보다 우선합니다.
+- `nextRecommendedPhase`가 `pending-routing-decision` 또는 `done-or-follow-up`이면 자동 채움하지 않고, 사용자가 명시적으로 `--task-type`을 주거나 brief을 보강한 뒤 다시 실행해야 합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-key jobs:tasks:8852
+```
+
+```bash
+scripts/okstra.sh --task-key jobs:tasks:8852 --task-type final-verification
+```
+
+### `--clarification-response`
+
+이전 run의 final report(`Section 5. Clarification Requests for the Next Run`에 사용자가 답변을 inline으로 채운 파일)를 다음 run으로 carry-in합니다.
+
+- 입력: `<previous-run>/reports/final-report-<task-type>-<seq>.md` 경로
+- 동작: 파일을 현재 run의 `instruction-set/clarification-response.md`로 복사하고, lead가 Section 0에서 prior `Q*` 행의 `Status`(`resolved` / `obsolete`)를 갱신한 뒤 진행합니다.
+- 사용 시점: `requirements-discovery`, `error-analysis`처럼 미해결 질문을 남기는 phase 이후, 사용자가 답변을 채워 다음 phase로 넘길 때.
+
+예:
+
+```bash
+scripts/okstra.sh \
+  --task-type implementation-planning \
+  --project-id jobs --task-group tasks --task-id 8852 \
+  --task-brief .project-docs/tasks/8852/BUG_REPORT.md \
+  --clarification-response .project-docs/okstra/tasks/tasks/8852/runs/2026-04-29/error-analysis/reports/final-report-2026-04-29_10-15-30.md
+```
+
+### `--resume-clarification`
+
+직전 `requirements-discovery` 또는 `error-analysis` run의 final report를 즉시 편집하고, 같은 phase를 자동으로 재실행합니다. `--clarification-response` 경로를 사용자가 직접 들고 다닐 필요가 없습니다.
+
+- 입력: task identity (`--project-id` + `--task-group` + `--task-id`, 또는 `--task-key <p>:<g>:<i>`)
+- 동작 순서:
+  1. task의 `runs/{requirements-discovery,error-analysis}/reports/final-report-*.md` 중 가장 최신 timestamp 파일을 자동 선택합니다.
+  2. `$EDITOR`(미설정 시 `vi`)로 해당 파일을 엽니다. 사용자는 Section 5의 `Q*` 행에 답변을 inline으로 채운 뒤 저장하고 종료합니다.
+  3. okstra가 같은 task-type으로 자기 자신을 `exec` 재호출하면서 편집된 파일을 `--clarification-response`로 carry-in 합니다.
+  4. 이후 confirmation, render, Claude handoff 흐름은 일반 실행과 동일합니다.
+- 명시적 `--task-type`을 함께 주면 그 task type의 reports/ 만 검색합니다. 생략 시 `error-analysis` → `requirements-discovery` 순으로 검색하고 timestamp가 더 큰 보고서를 사용합니다.
+- 다음 옵션과 함께 쓸 수 없습니다: `--render-only`, `--clarification-response`, `--approved-plan`.
+- `EDITOR`를 비대화형 도구(예: `true`)로 설정하면 답변 편집을 건너뛴 채 곧바로 재실행됩니다. 디버깅용으로만 권장합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --resume-clarification --task-key jobs:tasks:8852
+```
+
+```bash
+EDITOR=code\ -w scripts/okstra.sh --resume-clarification --project-id jobs --task-group tasks --task-id 8852
+```
+
+내부적으로는 다음과 동등합니다.
+
+```bash
+$EDITOR <project-root>/.project-docs/okstra/tasks/<group>/<id>/runs/<task-type>/reports/final-report-<latest>.md
+scripts/okstra.sh --task-type <same-type> \
+  --project-id <p> --task-group <g> --task-id <i> \
+  --task-brief <from manifest> \
+  --clarification-response <edited final-report-<latest>.md>
+```
+
+### `--project-root`
+
+대상 프로젝트의 절대 경로입니다. 명시하지 않으면 `okstra.sh` 가 다음 우선순위로 자동 해석합니다.
+
+1. cwd 또는 그 조상 디렉토리 중 `.project-docs/okstra/project.json` 보유 위치를 찾아 PROJECT_ROOT 로 채택합니다.
+2. 위가 실패하면 `git rev-parse --show-toplevel` 결과를 사용합니다.
+3. 모두 실패하면 즉시 에러로 종료합니다.
+
+해석된 PROJECT_ROOT 에서 첫 실행이라면 `<PROJECT_ROOT>/.project-docs/okstra/project.json` 이 다음 스키마로 자동 생성됩니다.
+
+```json
+{
+  "projectId": "<--project-id 인자 값>",
+  "projectRoot": "<resolved absolute path>",
+  "createdAt": "<ISO8601 UTC>",
+  "updatedAt": "<ISO8601 UTC>"
+}
+```
+
+이미 존재하면 `projectId` 일치 검사 후 `projectRoot`/`updatedAt` 만 갱신합니다. `projectId` 가 다르면 즉시 에러로 종료해 동일 디렉토리에서 두 개의 ID 가 혼용되는 것을 막습니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-type error-analysis --project-id jobs --project-root /Volumes/Workspaces/workspace/projects/jobs ...
+```
+
+### `--directive`
+
+사용자 의도를 자유 텍스트로 lead·worker·downstream skill에 전달하는 채널입니다. 값은 `instruction-set/analysis-material.md` 끝에 `## Directive` 섹션으로 임베딩되고, 동시에 `instruction-set/directive.txt`로 백업됩니다.
+
+용도:
+
+- 기본 heuristic을 뒤집고 싶을 때 — 예: "단일 XL task여도 Gantt 그려줘 (Phase 2개, 총 ~10d)", "Gantt 생략 사유를 명시해줘" (참고: `## Cumulative Timeline`은 schedule contract에서 제거되었으므로 더 이상 toggle 대상이 아닙니다)
+- 분석/계획의 강조점 지시 — 예: "rollout 리스크 우선 분석", "test 커버리지 부재를 별도 finding으로"
+- Phase/Step 분할이나 day 추정을 미리 제시 — 예: "Part 1: 4d, measure: 0.5d, Part 2: 4d, ops: 1d"
+
+해석 규칙:
+
+- lead·worker는 `analysis-material.md`를 이미 end-to-end로 읽으므로 별도 작업 없이 자동 전파됩니다.
+- skill 측은 자체 contract보다 user prompt를 **우선** 적용해야 하며 (예: `okstra-schedule` 스킬의 "Directive override (highest priority)" 절), heuristic을 뒤집은 경우 결과 문서에 그 사실을 한 줄로 표시합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-type implementation-planning ... \
+  --directive "Phase 2개(Part 1 ~4d, Part 2 ~5d, 순차)로 총 ~10d. Gantt 꼭 그려줘 (임계 경로 표시)."
+```
+
+### `--workers`
+
+이번 run에서 사용할 worker 목록을 직접 지정합니다.
+생략하면 기본값 `claude,codex,gemini,report-writer`를 사용합니다.
+지정하면 전달한 worker subset만 dedupe 후 기록됩니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-type implementation-planning --workers claude,codex --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
+
+### `--claude-model`
+
+`Claude worker`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_CLAUDE_MODEL` 또는 fallback `sonnet`을 사용합니다.
+
+### `--lead-model`
+
+`Claude lead`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_LEAD_MODEL` 또는 fallback `opus`를 사용합니다.
+
+### `--codex-model`
+
+`Codex worker`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_CODEX_MODEL` 또는 fallback `gpt-5.5`를 사용합니다.
+
+### `--gemini-model`
+
+`Gemini worker`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_GEMINI_MODEL` 또는 fallback `auto`를 사용합니다.
+
+### `--report-writer-model`
+
+`Report writer worker`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_REPORT_WRITER_MODEL` 또는 lead 기본값을 사용합니다.
+
+중앙 기본값 환경 변수는 아래와 같습니다.
+
+- `OKSTRA_DEFAULT_LEAD_MODEL`
+- `OKSTRA_DEFAULT_CLAUDE_MODEL`
+- `OKSTRA_DEFAULT_CODEX_MODEL`
+- `OKSTRA_DEFAULT_GEMINI_MODEL`
+- `OKSTRA_DEFAULT_REPORT_WRITER_MODEL`
+
+fallback 기본값은 아래와 같습니다.
+
+- `Claude lead`: `opus`
+- `Report writer worker`: `opus`
+- `Claude worker`: `sonnet`
+- `Codex worker`: `gpt-5.5`
+- `Gemini worker`: `auto`
+
+### `--related-tasks`
+
+간단한 연관 task 식별자 목록을 쉼표로 전달합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-type error-analysis --related-tasks scanner-regression,reply-ui --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
+
+연관 task는 참고용 메타데이터이며 현재 task key를 대체하지 않습니다.
+
+### `--render-only`
+
+실제 Claude 실행 없이 프롬프트와 task bundle만 생성합니다.
+
+이 모드에서는 아래를 수행하지 않습니다.
+
+- Claude 실행
+- `final-report-<task-type>-<seq>.md` 생성
+- `final-<task-type>-<seq>.status` 생성
+
+하지만 아래는 수행합니다.
+
+- stable task root 생성 또는 갱신
+- `task-manifest.json` 생성 또는 갱신
+- `task-index.md` 생성 또는 갱신
+- `instruction-set/` 생성 또는 갱신
+- `instruction-set/reference-expectations.md` 생성 또는 갱신
+- `instruction-set/final-report-template.md` 생성 또는 갱신
+- current `manifests/run-manifest-<task-type>-<seq>.json` 기록
+- `history/timeline.json` 갱신
+- project-level discovery pointer 생성 또는 갱신
+
+### `--refresh-assets`
+
+project-local `.claude/skills/`와 `.claude/agents/` 아래의 okstra mapped asset을 workspace source 기준으로 다시 생성합니다.
+기본 rerun에서는 기존 project-local asset을 유지합니다.
+
+
+## Interactive input flow
+
+interactive terminal에서 필수 인자 일부를 생략하면 `okstra`가 아래 항목을 순서대로 물을 수 있습니다.
+
+- `Project ID`
+- `Task Group`
+- `Task ID`
+- `Task Type`
+- `Task Brief Path`
+
+예를 들어 아래처럼 실행할 수 있습니다.
+
+```bash
+scripts/okstra.sh --render-only --task-type error-analysis
+```
+
+그러면 누락된 필수값을 stdin으로 입력받은 뒤, 최종 요약과 confirmation을 거쳐 진행합니다.
+
+## Confirmation flow
+
+interactive 실행에서는 실제 파일 생성 전에 아래 성격의 요약을 보여줍니다.
+
+- render-only 여부
+- task type
+- project id
+- task group
+- task id
+- task brief path
+- analysis target
+- related tasks
+- selected workers
+- lead model
+- configured worker models
+- task key
+- task root
+- current run dir
+
+이후 `Continue? [y/yes]:` 프롬프트가 표시되며, `y` 또는 `yes`가 아니면 실행하지 않고 종료합니다.
+
+`--yes`를 사용하면 이 confirmation flow 자체를 건너뜁니다.
+
+
+---
+
+## okstra Control Center — 설치 / 자주 쓰는 명령
+
+## okstra Control Center
+
+`okstra-ctl` 은 사용자 홈의 `~/.okstra/` 인덱스를 사용해 모든 타깃 프로젝트의 okstra run 을 가로질러 조회·모니터링·재실행할 수 있는 CLI 다.
+
+### 설치 (전역 wrapper)
+
+`okstra` 와 동일하게 `~/.local/bin/` 아래에 wrapper 를 두면 어디서든 호출 가능하다.
+
+```bash
+cat > ~/.local/bin/okstra-ctl <<'WRAPPER'
+#!/usr/bin/env bash
+exec /Volumes/Workspaces/workspace/projects/Okstra/scripts/okstra-ctl.sh "$@"
+WRAPPER
+chmod +x ~/.local/bin/okstra-ctl
+```
+
+(`~/.local/bin` 이 `PATH` 에 포함되어 있어야 한다.)
+
+### 자주 쓰는 명령
+
+| 목적 | 명령 |
+|---|---|
+| 작업한 프로젝트 목록 | `okstra-ctl projects` |
+| 최근 run 검색 | `okstra-ctl list --since 7d` |
+| 특정 프로젝트만 | `okstra-ctl list --project fontradar` |
+| 진행 중 run 보기 | `okstra-ctl tail active` |
+| 단일 run 결과 메타 | `okstra-ctl show <runId-or-prefix>` |
+| 결과 보고서 경로 | `okstra-ctl open <runId-or-prefix>` |
+| 단일 재실행 | `okstra-ctl rerun <runId-or-prefix> --yes` |
+| 다중 재실행 | `okstra-ctl rerun --filter --project X --status failed --yes` |
+| 가장 최근 재실행 | `okstra-ctl rerun last --project X --task-group Y --yes` |
+| 백필/재스캔 | `okstra-ctl reindex` |
+| 활성 run 재조정 | `okstra-ctl reconcile [--project <id|all>]` |
+| 배치 진행 | `okstra-ctl batch status <batch-id>` |
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",
@@ -16,7 +16,9 @@
     "bin/",
     "src/",
     "runtime/",
-    "README.md"
+    "docs/",
+    "README.md",
+    "README.kr.md"
   ],
   "engines": {
     "node": ">=18"

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.4.0",
-  "builtAt": "2026-05-12T03:09:54.795Z",
+  "package": "0.6.0",
+  "builtAt": "2026-05-12T04:57:34.255Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/profiles/implementation.md

@@ -14,16 +14,21 @@
   - `Report writer worker` is the **author** of the final-report file; `Claude lead` reviews and approves the produced draft and does NOT write the file itself (see `okstra-team-contract` and `okstra-report-writer` for the authoritative contract).
   - default model assignments are resolved from centralised defaults; the fallback values are `Claude lead`/`Claude executor`/`Report writer worker`=`opus`, `Claude verifier`=`sonnet`, `Codex verifier`=`gpt-5.5`, `Gemini verifier`=`auto`
   - all three verifier roles (`Gemini verifier`, `Codex verifier`, `Claude verifier`) must be attempted; the final verdict waits until each has either a result or an explicit terminal status
+  - **All-verifier-failure policy**: if every required verifier (`Gemini verifier`, `Codex verifier`, `Claude verifier`) ends with a non-result terminal status (`timeout`, `error`, `not-run`) — i.e. zero independent verdicts were produced — the run MUST end with status `blocked` and route to a follow-up `error-analysis` run. `Claude lead` MUST NOT substitute its own verdict in place of the missing verifier outputs; synthesis requires at least one independent verifier's verdict. If one or two verifiers fail but at least one returns a verdict, the run proceeds with the surviving verdict(s) and the final report MUST explicitly notate which verifiers were unavailable, with the captured error / timeout evidence per failed verifier.
   - unnamed generic parallel workers must not replace the required role roster, and no additional sub-agent dispatch is allowed beyond this roster
 - Tooling — read-only MCP availability:
   - `mcp__mysql-fontsninja-{common,fontradar,fontsninja,fonthelper}` (tools: `mysql_list_tables`, `mysql_describe_table`, `mysql_select_data`) may be queried by both executor and verifiers as a read-only cross-check (sanity-checking row counts after a migration script's dry-run, comparing observed schema against the plan's expectations, etc.); the canonical usage policy is in the task brief's `## Available MCP Servers` section, and any MCP-derived evidence MUST cite server, table, and the SELECT used. MCP MUST NEVER be used as a write path — schema/data mutations go through repository migration files, never through this MCP.
 - Pre-implementation gate (mandatory — refuse to start if any item fails):
   - the run brief MUST cite `--approved-plan <path>` pointing to a `final-report.md` produced by a prior `implementation-planning` run located under `runs/implementation-planning/.../reports/final-report.md`
-  - that file MUST contain a `User Approval Request` block AND a recorded user approval marker (e.g. `APPROVED:` line, `[x] Approved`, or equivalent unambiguous evidence). If only the request block exists without an approval marker, refuse to start with status `contract-violated`.
+  - that file MUST contain a `User Approval Request` block AND a recorded user approval marker matching one of the following line-anchored, case-insensitive forms (the runtime regex in `okstra_ctl.run._validate_approved_plan` enforces this and rejects the run with `PrepareError` before any prompt is generated): `APPROVED` (alone, followed by `:`, or end-of-line), `[x] Approved`, or `User Approval: APPROVED|granted|yes`. Free-form approvals such as "lgtm", "go ahead", or paraphrased confirmations are intentionally NOT accepted; if the user's approval is informal, re-edit the plan file to add one of the exact markers above before invoking the implementation run.
   - the file's `Recommended option` and its bite-sized step list become the authoritative scope for this run; any deviation must be justified in the final report and routed back to a new `implementation-planning` run instead of being silently expanded.
 - Pre-implementation context exploration (executor before first edit):
   - re-read the approved plan end-to-end and extract: file list, step order, validation commands, rollback path
   - inspect the current state of every file the plan names; if any file has changed materially since the plan was written, stop and route to a new `implementation-planning` run instead of editing speculatively
+  - "materially changed" means: the function, class, section, or behaviour the plan targets has been edited, renamed, moved, removed, or otherwise altered in a way that invalidates the plan's reasoning. Cosmetic edits (whitespace, comment-only changes, unrelated function modifications elsewhere in the same file) do NOT trigger a re-plan; cite the diff (`git log --oneline <plan-created-at>..HEAD -- <file>`) in the final report and proceed.
+  - distinguish the two file-scope rules (they are not in conflict):
+    - **drift rule** (this section): if a file *named in the plan* has materially drifted, refuse to edit and route back to planning. This protects trust in the approved scope.
+    - **out-of-plan rule** (Allowed actions section below): if a step *requires touching a file NOT in the plan list*, that is permitted with `Out-of-plan edits` justification. This handles honest scope discovery during execution.
   - confirm the test/build commands referenced in the plan still exist and run from a clean state
 - Allowed actions during the run:
   - **Edit / Write on any project file** (no path whitelist — scope is bounded by the approved plan's file list, not by directory). Editing files outside the plan's list is permitted only when strictly needed to satisfy a step, and MUST be recorded in the final report's `Out-of-plan edits` block with rationale.
@@ -53,7 +58,10 @@
   - **Validation evidence**: actual command output (stdout/stderr) for every `pre / mid / post` validation command from the plan. Truncated output is acceptable but the command line and exit code MUST be exact. No paraphrasing of test results.
   - **TDD evidence (when applicable)**: for steps that should be TDD-ordered, show the failing-test output BEFORE the implementation commit and the passing-test output AFTER, with commit SHAs framing the transition.
   - **Verifier results**: a section per verifier (`Gemini verifier`, `Codex verifier`, `Claude verifier`) containing their independent verdict (PASS / CONCERNS / FAIL), their cited diff snippets, and any fix recommendations they declined to apply. `Claude lead` synthesises a unified verdict but MUST preserve dissent — do not collapse three opinions into one paragraph.
-  - **Rollback verification**: confirmation that the plan's rollback path is still valid after the changes (e.g. revert SHA exists, feature flag toggle works, migration down step is reachable). Dry-run rollback is preferred when feasible.
+  - **Rollback verification**: confirmation that the plan's rollback path is still valid after the changes. Strength of verification depends on the change category:
+    - **Pure code changes** (no persisted state, no infra mutation): a reachable revert SHA is sufficient. Record the exact `git revert <SHA>` command that would undo the change, and confirm `git rev-parse <SHA>` resolves.
+    - **Feature-flag-gated changes**: confirm the off-switch path was exercised in this run's validation evidence (i.e. one of the validation commands ran with the flag off and succeeded). A plan that ships a flag without exercising the off-path does NOT satisfy this requirement.
+    - **Schema migrations, config-format changes, or any change with persisted state**: a **dry-run of the rollback step is mandatory**, not preferred. Record the exact rollback command and its captured exit code / stdout. If the migration tool offers no dry-run mode (`--dry-run`, `--plan`, equivalent), the executor MUST refuse to claim rollback verification and instead end the run with a routing recommendation back to `implementation-planning` for a safer rollback strategy. Skipping this step on a stateful change is treated as a `contract-violated` outcome by `final-verification`.
   - **Routing recommendation for `final-verification`**: brief note on whether the changes are ready for final-verification phase or need a new error-analysis / planning loop first.
 - Self-review pass before finalising the report (`Claude lead` runs this; do not delegate to a generic subagent):
   1. **Plan coverage** — every step in the approved plan's recommended option must point to a commit (or an explicit `Skipped: <reason>` entry). List gaps.
@@ -61,7 +69,11 @@
   3. **Out-of-plan honesty** — files in the diff that are NOT in the plan list must appear in the `Out-of-plan edits` block. Cross-check with `git diff --name-only`.
   4. **Verifier dissent preserved** — if the three verifiers disagree, the disagreement is visible in the report? Synthesis hides nothing?
   5. **Forbidden action audit** — `git push`, publish, deploy, migration, third-party write commands: scan the run's session transcripts for any occurrence and confirm none happened.
-  6. **Placeholder scan** — committed code searched for TBD / TODO / "handle edge cases" strings introduced by this run? (Pre-existing TODOs in untouched code are out of scope.)
+  6. **Placeholder scan** — restrict the scan to lines this run actually introduced; pre-existing placeholders in unchanged regions of touched files are out of scope. Required command (substitute `<base>` with the parent of the first commit in this run's commit list):
+     ```
+     git diff <base>..HEAD | grep -E '^\+[^+].*\b(TBD|TODO|FIXME|XXX|implement later|handle edge cases|similar to|placeholder)\b' || echo 'clean'
+     ```
+     Only newly-added lines (those starting with `+` and not part of the `+++` header) are inspected. If output is anything other than `clean`, the run MUST either remove the placeholders before finalising or record an explicit justification per occurrence in the final report.
 - Skill provenance (for maintainers — these skills are referenced as inspiration, NOT invoked at runtime):
   - The pre-implementation gate, "Plan coverage" and "Evidence completeness" self-review items are adapted from the `executing-plans` skill (inline mode). The skill's "subagent-driven vs inline" choice prompt and its plan-document-header conventions are intentionally not adopted — okstra owns lifecycle handoff.
   - The "TDD evidence" requirement and the failing-test-before-implementation ordering preference are adapted from `test-driven-development`. Strict enforcement is relaxed where the touched area has no test infrastructure; in those cases the executor must add at minimum a regression test and record a justification.

package/runtime/python/okstra_ctl/workflow.py

@@ -98,7 +98,9 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - source edits or Bash mutations performed by any verifier role (`Gemini verifier`, `Codex verifier`, `Claude verifier` are read-only — recommend, do not apply)\n"
             "  - dispatching parallel sub-agents beyond the required worker roster\n"
             "  - silent scope expansion: every file edited outside the approved plan list MUST appear in the `Out-of-plan edits` block with rationale\n"
-            '  - leaving placeholders such as TBD / TODO / "implement later" / "handle edge cases" in committed code\n'
+            '  - leaving placeholders such as TBD / TODO / "implement later" / "handle edge cases" in newly-added lines of this run (check via `git diff <base>..HEAD | grep -E \'^\\+[^+].*\\b(TBD|TODO|FIXME|XXX|implement later|handle edge cases|similar to|placeholder)\\b\'`; pre-existing strings in untouched regions are out of scope)\n'
+            "  - lead substituting its own verdict when every required verifier (`Gemini verifier`, `Codex verifier`, `Claude verifier`) returned a non-result terminal status (`timeout`/`error`/`not-run`); in that case the run MUST end as `blocked` with routing recommendation back to `error-analysis`, never with a lead-only verdict\n"
+            "  - claiming rollback verification on a schema migration, config-format change, or any persisted-state mutation without a recorded dry-run of the rollback step and its captured exit code\n"
             '  - declaring overall task acceptance — that is `final-verification` ownership; this phase reports only "ready for final-verification" or "needs new planning loop"\n'
             "  - delegating the self-review pass to a generic subagent — `Claude lead` must run it"
         ),

package/src/install.mjs

@@ -226,6 +226,13 @@ async function installLinkMode(repoPath, paths, opts) {
     process.stdout.write(`  dev-link stamp: ${repoAbs}\n`);
     process.stdout.write(`  version stamp: ${paths.package}\n`);
     process.stdout.write("done.\n");
+    process.stdout.write(
+      "\nNext step: register the current project.\n" +
+        "  cd <your project> && npx -y okstra@latest setup --project-id <id>\n" +
+        "  (or run /okstra-setup inside a Claude Code session)\n" +
+        "\nTip: to use a bare 'okstra' command instead of npx, run:\n" +
+        "  npm i -g okstra\n",
+    );
   }
   return 0;
 }
@@ -401,6 +408,13 @@ export async function runInstall(args) {
   if (!opts.quiet) {
     process.stdout.write(`  version stamp: ${paths.package}\n`);
     process.stdout.write("done.\n");
+    process.stdout.write(
+      "\nNext step: register the current project.\n" +
+        "  cd <your project> && npx -y okstra@latest setup --project-id <id>\n" +
+        "  (or run /okstra-setup inside a Claude Code session)\n" +
+        "\nTip: to use a bare 'okstra' command instead of npx, run:\n" +
+        "  npm i -g okstra\n",
+    );
   }
   return 0;
 }