okstra 0.184.0 → 0.185.1

package/runtime/python/okstra_ctl/wizard.py

@@ -2733,6 +2733,8 @@ def _build_task_type(state: WizardState) -> Prompt:
     recommended_suffix = t["options"].get("_RECOMMENDED_SUFFIX", "")
     rerun_suffix = t["options"].get("_RERUN_SUFFIX", "")
     next_suffix = t["options"].get("_NEXT_SUFFIX", "")
+    approve_suffix = t["options"].get("_APPROVE_SUFFIX", recommended_suffix)
+    blocked_rerun_suffix = t["options"].get("_BLOCKED_RERUN_SUFFIX", rerun_suffix)
     description_by_type = dict(TASK_TYPES)
     options: list[Option] = []
 
@@ -2758,10 +2760,21 @@ def _build_task_type(state: WizardState) -> Prompt:
     # `ready` 가 아니면 추천은 비고, 아래 `currentPhase` 재실행 옵션이 남는다.
     # 실패한 run 의 포인터가 `{"phase": "", "status": "blocked"}` 라는 점에서
     # 그것이 맞는 제안이다 — 그 옵션은 포인터가 아니라 `currentPhase` 에서 온다.
+    # 계획 승인 대기는 `awaitingApproval` 로 표시한다. 구현이 추천이지만 먼저
+    # 승인을 받아야 하므로 접미사로 구분한다. 열린 C-NNN 때문에 blocked 면
+    # 재실행은 답이 기록된 뒤에만 고르라고 접미사로 말한다.
     recommended = (revision_requested or state.task_type
                    or next_phase.autofill_task_type({"workflow": workflow}))
     if not recommended and not workflow:
         recommended = TASK_TYPE_VALUES[0]
+    pointer = next_phase.promote(workflow.get("nextRecommendedPhase"))
+    if workflow.get("awaitingApproval") is True and recommended == "implementation":
+        recommended_suffix = approve_suffix
+    if (
+        pointer["status"] == next_phase.STATUS_BLOCKED
+        and (workflow.get("currentPhase") or "") == "implementation-planning"
+    ):
+        rerun_suffix = blocked_rerun_suffix
     add(recommended, recommended_suffix)
     add(workflow.get("currentPhase") or "", rerun_suffix)
     add(_phase_after(recommended), next_suffix)

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

@@ -0,0 +1,108 @@
+---
+name: okstra-chat
+description: Use when the user wants to create or join a global okstra chat room, send a message to everyone or to one participant, read unread arrivals, or reopen the inbox. Trigger words include "okstra chat", "okstra-chat", "chat room", "join the room", "send a chat message".
+---
+
+# okstra-chat
+
+Cross-session rooms in the global okstra home. Not a project task artifact.
+Do not write JSON. Call `okstra chat` and read its fixed text.
+
+Rooms are independent of tasks and runs. A participant is this host session.
+The display name is typed at join. Do not invent a default name.
+
+## When to use
+
+- The user wants a room that a Claude lead and a Grok lead can both join.
+- The user wants to send a message, see unread arrivals, or reopen the inbox.
+
+## Step 0: CLI
+
+Run as a separate Bash tool call with literal leading token:
+
+```bash
+okstra chat --help
+```
+
+If `okstra` is not on PATH, tell the user:
+
+`okstra not installed — run npx okstra@latest install once, then retry this skill.`
+
+Do not use `npx` from this skill.
+
+## Step 1: Create or join
+
+Ask one question: create a room, or join an existing room.
+
+If the host has a native picker, use it. Otherwise print a numbered list.
+
+### Create
+
+1. Ask for the room name as free input.
+2. Run `okstra chat create --room <room>`.
+3. Ask for the display name as free input. Do not suggest a generated name.
+4. Run `okstra chat join --room <room> --name <display>`.
+
+### Join
+
+1. Run `okstra chat rooms`.
+2. If the output is `no rooms`, say so and offer create.
+3. Otherwise pick a room from that list (picker, or numbered list if the picker limit is exceeded).
+4. Ask for the display name as free input.
+5. Run `okstra chat join --room <room> --name <display>`.
+
+`--name` is required. An empty name, `all`, or a name already in the room fails.
+
+## Step 2: Unread
+
+```bash
+okstra chat unread --room <room> --as <display>
+```
+
+Show the rows. Each row is `id:time:@from:to:body`. Recipient `all` stays `all`. Sender is always `@name`.
+
+If the output is `no unread`, do not ack.
+
+If there are unread rows, always run:
+
+```bash
+okstra chat ack --room <room> --as <display> --through <id>
+```
+
+Use the last unread row's id. CLI unread does not move the cursor; this ack does.
+
+## Step 3: Next action
+
+Ask: send, unread, inbox, log, or done.
+
+There is no ack menu item. Choosing unread again shows the rows then acks, same as Step 2.
+
+### Send
+
+1. Run `okstra chat members --room <room>`.
+2. Pick the recipient from `all` plus those names except the current display name (`--as`). Filter after `okstra chat members`. Do not pass `--as` to `members`. Recipient is required.
+3. Ask for the body as free input.
+4. Run `okstra chat send --room <room> --as <display> --to <all|name> --body <text>`.
+
+### Inbox
+
+```bash
+okstra chat inbox --room <room> --as <display>
+```
+
+This is every arrival to `@you` or `all`, including messages already acked and messages you sent to `all` or to yourself. Inbox does not move the cursor.
+
+### Log
+
+```bash
+okstra chat log --room <room> --as <display>
+```
+
+The whole room, including messages not addressed to you. Log does not move the cursor.
+
+## Rules
+
+- Call only `okstra chat`. Do not open files under the chat store.
+- Do not treat chat rows as evidence for a finding, verdict, or assignment.
+- Workers may run the same commands with `--name` and `--as`. Joining is optional.
+- Do not generate a display name from the provider, model, or execution label.

package/runtime/skills/okstra-inspect/facets/status.md

@@ -95,12 +95,13 @@ It has already promoted legacy values.
 The status response always includes one of:
 
 1. **Resume current run** — if `latestResumeCommandPath` exists, display that path.
-2. **Restart current phase** — task can be re-run with the same `task-key` and current `taskType`.
-Branches 3–5 are decided by `workflow.nextRecommendedPhase.status` alone — one status, one branch, no other field consulted:
+2. **Ask the user to approve** — if `workflow.awaitingApproval` is true. Tell the user to approve the plan (`okstra-run` with `--task-type implementation`, which asks `approve_plan_confirm`, or `--approve`). Quote `nextRecommendedPhase.rationale`. A `ready` pointer to `implementation` here means implementation is next after approval, not that it may launch as if already approved. Do not re-run `implementation-planning`.
+3. **Restart current phase** — only when `awaitingApproval` is false and the pointer is not `ready`. The task can be re-run with the same `task-key` and current `taskType`.
+Branches 4–6 are decided by `workflow.nextRecommendedPhase.status` when `awaitingApproval` is false — one status, one branch:
 
-3. **Start next phase** — `status` is `ready`. Propose `nextRecommendedPhase.phase` as the next run's `--task-type` and quote its `rationale` as the reason. This is the only status under which a named phase may be launched, so it is the only branch that proposes a run. A `ready` pointer to `release-handoff` already implies an `accepted` final-verification verdict (the report validator refuses that routing target otherwise), so do not re-gate it here.
-4. **Need more information** — `status` is `pending` (the last run did not settle where this task goes next) or `blocked` (it did settle, and the answer is that something outside the run has to change first). Neither proposes a run, and a leftover `phase` name does not change that — `prepare` keeps the name when it lowers a pointer to `pending`, so read `status`, not the emptiness of `phase`. Show the `rationale`, and for `blocked` state what it names as the obstacle. The way forward is a fresh brief, a clarification response, or a re-run of the current phase — not a next-phase launch.
-5. **Task complete (terminal)** — `status` is `terminal`: the task lifecycle ends here. This is **not** a "next phase" — do not propose a new okstra run. Surface the latest report and ask the user whether any follow-up task should be opened separately.
+4. **Start next phase** — `status` is `ready` and `awaitingApproval` is false. Propose `nextRecommendedPhase.phase` as the next run's `--task-type` and quote its `rationale` as the reason. This is the only status under which a named phase may be launched without a prior approval ask, so it is the only branch that proposes a run. A `ready` pointer to `release-handoff` already implies an `accepted` final-verification verdict (the report validator refuses that routing target otherwise), so do not re-gate it here.
+5. **Need more information** — `status` is `pending` (the last run did not settle where this task goes next) or `blocked` (it did settle, and the answer is that something outside the run has to change first). Neither proposes a run, and a leftover `phase` name does not change that — `prepare` keeps the name when it lowers a pointer to `pending`, so read `status`, not the emptiness of `phase`. Show the `rationale`, and for `blocked` state what it names as the obstacle. After `implementation-planning`, the first action is `okstra-user-response` on the named `C-NNN` ids; do not re-run planning until those answers exist, and do not start implementation.
+6. **Task complete (terminal)** — `status` is `terminal`: the task lifecycle ends here. This is **not** a "next phase" — do not propose a new okstra run. Surface the latest report and ask the user whether any follow-up task should be opened separately.
 
 ### status.4 — Update workStatus (write)
 

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

@@ -241,7 +241,7 @@ If an action has an unknown `command`, `key`, or `scope`, stop and report the wi
 
 Before rendering the next phase's bundle — and between worker rounds within a phase (reverify/critic/gapverify batches), after you have collected that round's results and token usage and before you dispatch the next round — close the panes of the dispatches that finished in the prior round so they do not accumulate, in two passes. First count: `okstra team reclaim --project-root <projectRoot> --run-manifest <RUN_MANIFEST_PATH> --dry-run` closes nothing and prints one `<paneId>\t<kind>` line per pane it would close — count those lines as `<n>`. Then run the same command **without** `--dry-run` to close them, and emit `PROGRESS: phase-batch-cleanup panes=<n>` with that count at the batch boundary. The command reads each dispatch's recorded status, so an in-progress worker keeps its pane whichever moment you call it. It closes only the panes okstra opened and recorded — a pane the harness opened for its own teammate carries no recorded id and is not okstra's to close. `shutdown_request` alone only idles the agent and frees no pane, so it stays part of the run-end sequence for roster/token hygiene. A `cli-wrapper` run holds no pane at all, so `<n>` is `0` — still emit the checkpoint.
 
-Before you ask the user for any approval, clarification, or decision after workers have been dispatched, run the same two passes first: `okstra team reclaim … --dry-run` to count the panes, then the same command without `--dry-run` to close them, emit `PROGRESS: phase-gate-cleanup panes=<n>`, and `TaskStop` each completed worker. A `TaskStop` by itself idles the task but leaves the pane open — the `team reclaim` call is what closes it. This keeps a user gate from being shown while finished worker panes remain; in-progress dispatches keep their panes.
+Before you ask the user for any approval, clarification, or decision after workers have been dispatched, run the same two passes first: `okstra team reclaim … --dry-run` to count the panes, then the same command without `--dry-run` to close them, emit `PROGRESS: phase-gate-cleanup panes=<n>`, and `TaskStop` each completed worker. A `TaskStop` by itself idles the task but leaves the pane open — the `team reclaim` call is what closes it. This keeps a user gate from being shown while finished worker panes remain; in-progress dispatches keep their panes. Then follow `prompts/lead/okstra-lead-contract.md` "User confirmation before an approval blocker": read cited plan items, worker findings, and files before asking, and ask in the user's language with each option's outcome.
 
 Build the `okstra render-bundle` invocation from `outcome.renderArgv`, passing every token verbatim and in order (including empty strings — they are intentional `use phase default` markers).
 
@@ -390,4 +390,4 @@ Do not read the wizard state file directly. `okstra wizard outcome` exposes any
 
 - Echo each captured answer (`result.echo`) on one short line so the user sees what was registered.
 - Never invent identity; if a `text` prompt returns an empty answer where the wizard rejects it, the user must retry.
-- After Step 6, begin the lead workflow without re-summarizing the skill itself. For a single run, the end of Step 6 is the end of the run — but in an unattended chain where `orchestration.chainStages` has 2+ elements, repeat Step 6 per stage until Step 7's queue is empty (or it stops at a "not ready" / exception gate), then finish.
+- After Step 6, begin the lead workflow without re-summarizing the skill itself. For a single run, the end of Step 6 is the end of the run — but in an unattended chain where `orchestration.chainStages` has 2+ elements, repeat Step 6 per stage until Step 7's queue is empty (or it stops at a "not ready" / exception gate), then finish. After an `implementation-planning` run, read `workflow.awaitingApproval` and the next-phase pointer from the task manifest. If awaiting approval, the next sentence to the user is to approve the plan (`okstra-run` → `implementation`, or `--approve`). Do not start another planning run. If the pointer is `blocked`, name the rationale and send the user to `okstra-user-response`; do not re-run planning until those answers exist.

package/runtime/skills/okstra-user-response/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: okstra-user-response
 description: >-
-  Use this to answer an okstra task's open clarification questions in-session without hand-editing a report or sidecar. It projects the available tasks and one report as fixed text, asks one question at a time, confirms the user's exact answers, and publishes only the user-owned user-responses sidecar through a typed transaction. NOT for starting a run, inspecting a finished task, or generating a brief.
+  Use this to answer an okstra task's open clarification questions in-session without hand-editing a report or sidecar. It projects the available tasks and one report as fixed text, reads cited context before asking, asks one question at a time in the user's language with each option's outcome, confirms the user's exact answers, and publishes only the user-owned user-responses sidecar through a typed transaction. NOT for starting a run, inspecting a finished task, or generating a brief.
 ---
 
 # OKSTRA User Response
@@ -13,26 +13,28 @@ The model-facing commands are fixed text reads and typed transaction writes:
 | Command | Purpose |
 |---|---|
 | `user-response list-view` | Show tasks that still await user input. |
-| `user-response show-view` | Show questions, choices, resolved context, and current response state. |
+| `user-response show-view` | Show questions, choices, why asked, linked plan items, cited artifacts, resolved context, and current response state. |
 | `user-response begin` | Open a sidecar transaction for one report identity. |
 | `user-response answer` | Add or replace one validated clarification answer. |
 | `user-response plan-decision` | Record an explicit plan decision in the transaction. |
 | `user-response legacy-report-authoring` | Record legacy report-authoring permission for report contract 2.0 only. |
 | `user-response finalize` | Atomically merge and publish the user-owned sidecar. |
 
-Do not use the automation-oriented `list` or `show` commands. Do not open a report record to select fields. The fixed views provide every value this skill may use.
+Do not use the automation-oriented `list` or `show` commands. Do not open a report record to select fields. Question text and `options[]` come only from the fixed views. Cited files listed in `show-view` are read only to explain those options.
 
 ## Step 0: Preflight
 
+Use the registered host ID that the current harness declares for this session. Do not infer it from an executable or `PATH`. Do not substitute `claude-code`.
+
 <!-- BEGIN FRAGMENT: bash-invocation-rule -->
 Run one Bash tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match):
 <!-- END FRAGMENT: bash-invocation-rule -->
 
 ```bash
-okstra preflight --runtime claude-code
+okstra preflight --runtime <host-runtime>
 ```
 
-On `Okstra preflight: failed`, show `Reason` and `Recovery`, then stop. On `Okstra preflight: ready`, carry the fixed `Project root` and `Project ID` lines as literal values.
+On `Okstra preflight: failed`, show `Reason` and `Recovery`, then stop. On `Okstra preflight: ready`, carry the fixed `Project root`, `Project ID`, `Runtime`, and `Relay contract` lines as literal values.
 
 <!-- BEGIN FRAGMENT: preflight-outdated-cli -->
 If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).
@@ -48,6 +50,17 @@ okstra paths --field home
 Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
 <!-- END FRAGMENT: python-bootstrap-note -->
 
+## Host picker
+
+Every choice this skill asks — the task pick, each clarification, an explicit plan decision, and the final record confirmation — uses the same host picker as `okstra-run`.
+
+Read the absolute path in the fixed `Relay contract` line. In that file, take the `Wizard interaction relay` JSON. Intersect its `semanticFunctions` with the functions this session can actually call, using each `interactions` kind's `function` field. The live harness does not expose tools named `native_single_select`. Keep `native-single` only when `native_single_select` is in that intersection. Keep `nativeLimits`. If `Relay contract` is `-`, native-single is unavailable.
+
+- When `native-single` is available and the option count fits `nativeLimits` (unique labels, within min/max): call `interactions.native-single.function` once with one question and every option as `{label, description}` in original order. Do not print a numbered list in chat while the native tool is available. Claude Code's function is `AskUserQuestion`, Grok's is `ask_user_question`, Codex's is `request_user_input` — copy the relay field; do not substitute one name for another.
+- Otherwise render a 1-based numbered Markdown list and wait for the next message. Do not drop options to force the native tool.
+
+Never invent a picker function. Never ask the user to type a number when the native tool is available.
+
 ## Step 1: Select a task from the fixed list view
 
 ```bash
@@ -56,7 +69,7 @@ okstra user-response list-view --home <resolved-home> --project <projectId> --li
 
 The view gives `Task key`, `Task type`, `Report`, open-item counts, and readability status. If the count is zero, answer `No task has open clarification items.` and stop. Do not continue with an unreadable entry.
 
-Present up to three task choices. The final picker option is `Enter directly`, where the user may provide a report path or task key.
+Present up to three task choices through the host picker. The final picker option is `Enter directly`, where the user may provide a report path or task key.
 
 ## Step 2: Read the fixed report view
 
@@ -64,21 +77,41 @@ Present up to three task choices. The final picker option is `Enter directly`, w
 okstra user-response show-view --report <reportPath> --project-root <projectRoot>
 ```
 
-The view contains the report identity, contract version, every open clarification question, its expected form, its current response and disposition, its options, approval context, plan option candidates, current plan decision, and resolved context. It is the only report-information source for this skill.
+The view contains the report identity, contract version, every open clarification question, its expected form, its current response and disposition, its options, approval context, plan option candidates, current plan decision, resolved context, why the row is asked, linked plan items, and cited artifacts. Question text and `options[]` come only from this view. Do not open a report record to select fields.
 
 Each entry in `options[]` corresponds to `{role, answer, rationale, scopeImpact, addedWork, directionChange, disposition}`. Put the `recommended` option first and suffix its label with `(Recommended)`. Then put the alternatives in view order and finish with `Enter directly`.
 
-Contract 3.0 options also expose `reach` and `scopeEffects`. Contract 3.0 approval-blocking rows expose `approvalContext`. Present those values exactly as the view prints them.
+Contract 3.0 options also expose `reach` and `scopeEffects`. Contract 3.0 approval-blocking rows expose `approvalContext`.
+
+When an axis says `not stated in the report`, repeat that text. Do not infer missing report-owned impact. The skill must **never invent it**.
 
-Each option description uses all three impact axes in this order:
+## Step 2b: Investigate cited context before asking
 
-> `<rationale>` — Scope: `<scopeImpact>` · Added work: `<addedWork>` · Direction: `<directionChange>`
+Do not present a picker from the raw field dump. For each still-open item, read the investigation list the view printed:
 
-When an axis says `not stated in the report`, repeat that text. Do not infer missing impact. The skill must **never invent it**.
+1. Every `Cited artifacts:` `path:line` — open that file under the project root from preflight. The line number is the starting point, not a license to skip the surrounding function or section.
+2. Every `Linked plan items:` definition and every `Context:` definition.
+
+Stop at that list. Do not search the rest of the repository for extra files. If a cited path is missing or unreadable, say so in the question; do not guess its contents.
+
+Investigation explains. It never adds an option, drops an option, or changes the answer that `--option-number` will record.
 
 ## Step 3: Ask one clarification at a time
 
-For each item that still needs an answer, show its position, ID, blocking effect, question, expected form, and resolved context. Use one single-select question per clarification.
+Ask in the user's language. Do not lead with `Kind`, `Blocks`, `Expected form`, or `C-NNN`. The question body is:
+
+1. Why this is being asked (`Why asked`, restated so a non-author of the report can follow it).
+2. What is already decided (`Context` and linked plan items, in one or two sentences).
+3. The fork (`Question`, restated as a choice the user can act on).
+4. What stays blocked if they do not answer (`Blocks=approval` → the plan cannot be approved; `Blocks=next-phase` → the next phase cannot start cleanly).
+
+Keep the row id at the end of the question, in parentheses, so the later transaction can name it.
+
+Use one single-select question per clarification, through the host picker. Each option description uses this order:
+
+> If you pick this: `<addedWork>`. What it reverses: `<directionChange>`. Scope: `<reach or scopeImpact>`. Why it is on the board: `<rationale>`.
+
+When investigation quoted a cited file, add one more sentence that names the path. That sentence does not replace a `not stated in the report` axis.
 
 Use the displayed values to confirm the user's choice. Do not copy a predefined option's answer, disposition, reach, or scope effects into command arguments. The typed command resolves those report-owned fields from its option number.
 
@@ -88,15 +121,16 @@ Use the displayed values to confirm the user's choice. Do not copy a predefined
 | Enters an answer | the user's text verbatim | `answer` |
 | Asks for the item to be presented again | the user's request verbatim | `reframe` |
 
-Copy `kind` from the view. A `reframe` does not satisfy the gate. If the user asks what an item means, explain only from the view and ask the same item again.
+Copy `kind` from the view. A `reframe` does not satisfy the gate. If the user asks what an item means, explain from the view plus the cited files already read, then ask the same item again.
 
 ## Step 4: Confirm the complete response
 
-Echo each clarification ID, kind, disposition, value, and rationale. Include any explicit plan decision or legacy report-authoring decision. Ask:
+Echo each clarification ID, kind, disposition, value, and rationale. Include any explicit plan decision or legacy report-authoring decision. Ask through the host picker, two options:
 
-> Record it as shown above? Reply `confirmed` to publish the sidecar.
+1. `Record as shown` (Recommended)
+2. `Change an answer`
 
-Do not start a transaction until the user clearly confirms. If the user changes an item, show the complete response again and reconfirm.
+Do not start a transaction until the user picks `Record as shown`. If they pick `Change an answer`, show the complete response again and reconfirm with the same picker. Do not ask them to type `confirmed`.
 
 ## Step 5: Begin the typed transaction
 

package/runtime/validators/validate-run.py

@@ -642,6 +642,35 @@ def write_json(path: Path, payload: dict) -> None:
     path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
 
 
+def _report_already_approved(report_data: Mapping[str, Any] | None) -> bool:
+    if not isinstance(report_data, Mapping):
+        return False
+    frontmatter = report_data.get("frontmatter")
+    return isinstance(frontmatter, Mapping) and frontmatter.get("approved") is True
+
+
+def _derive_awaiting_approval(
+    *,
+    existing: bool,
+    validation_status: str,
+    current_phase: str,
+    pointer: Mapping[str, str],
+    report_data: Mapping[str, Any] | None,
+) -> bool:
+    """planning 이 승인 가능한 plan-ready 를 남기면 올리고, implementation
+    이 그 승인을 소비하면 내린다. 차단 게이트나 열린 Blocks=approval 은
+    포인터가 blocked 라 올리지 않는다."""
+    if validation_status == "passed" and current_phase == "implementation":
+        return False
+    if validation_status == "passed" and current_phase == "implementation-planning":
+        return (
+            pointer.get("phase") == "implementation"
+            and pointer.get("status") == next_phase.STATUS_READY
+            and not _report_already_approved(report_data)
+        )
+    return existing
+
+
 def update_workflow_metadata(
     run_manifest: dict,
     task_manifest: dict,
@@ -693,7 +722,8 @@ def update_workflow_metadata(
             next_recommended_phase = next_phase.make(
                 phase=projected["phase"],
                 status=projected["status"],
-                rationale=(
+                rationale=projected["rationale"]
+                or (
                     "리포트 라우팅에서 투영됨. 리드가 쓴 값과 근거는 "
                     "nextRecommendedPhaseCorrection.authored 에 있다."
                 ),
@@ -713,16 +743,16 @@ def update_workflow_metadata(
             status=next_phase.STATUS_BLOCKED, rationale=authored["rationale"]
         )
 
-    awaiting_approval = workflow.get("awaitingApproval")
-    if not isinstance(awaiting_approval, bool):
-        awaiting_approval = False
-    # 승인 게이트(`frontmatter approved`)는 implementation 진입 직전에 한 번만 의미를 가진다.
-    # implementation run 이 검증을 통과했다는 것은 `_validate_approved_plan` 이 이미 사용자
-    # 승인 플래그(frontmatter `approved: true`)를 소비했다는 뜻이므로, 이 시점에
-    # awaitingApproval 플래그를 명시적으로 내려 다음 phase 의 status 뷰에서 stale 상태로
-    # 남지 않게 한다.
-    if validation_status == "passed" and current_phase == "implementation":
-        awaiting_approval = False
+    awaiting_existing = workflow.get("awaitingApproval")
+    if not isinstance(awaiting_existing, bool):
+        awaiting_existing = False
+    awaiting_approval = _derive_awaiting_approval(
+        existing=awaiting_existing,
+        validation_status=validation_status,
+        current_phase=current_phase,
+        pointer=next_recommended_phase,
+        report_data=report_data,
+    )
 
     last_safe_checkpoint = workflow.get("lastSafeCheckpoint", {})
     if not isinstance(last_safe_checkpoint, dict):
@@ -3562,6 +3592,7 @@ def validate_final_report_data(
         _validate_clarification_evidence_note(data, failures)
         _validate_approval_clarification_backtrace(data, failures)
         _validate_rerun_guidance(data, failures)
+        _validate_approval_guidance(data, failures)
         _validate_variation_point_analysis(
             (data.get("implementationPlanning") or {}).get("variationPointAnalysis"),
             resolve_architecture(_project_root_from_report(report_path)),
@@ -4147,10 +4178,11 @@ def _stage_scope_bucket(item: dict, pbv: dict) -> str:
 
     Returns `in-scope` (may block), `observed` (only frozen stages), or
     `deferred` (only stages not yet startable). Anything unresolvable is
-    `in-scope`: an absent ledger is no basis to narrow, and an item with no
-    `stageScope` belongs to the plan as a whole — `P-Opt-*` and `P-Var-*` live
-    there permanently, and scoping them out would stop an unrequested-work
-    verdict from blocking a start.
+    `in-scope`: an absent ledger is no basis to narrow. Plan-wide items
+    (`P-Opt-*`, `P-Var-*`, `P-Dep-*`, `P-Dir-1`) with no `stageScope` stay
+    in-scope. An unscoped `P-Val-*` / `P-Req-*` / `P-Rb-*` stays in-scope only
+    until a stage is `done`; after that it is `deferred` so a re-plan does not
+    re-score the whole checklist.
 
     디스패치 큐와 같은 함수를 쓴다. 검증기가 다른 통을 내면 워커가 안 본
     항목이 승인을 막거나, 본 항목이 게이트에서 빠진다.
@@ -6130,16 +6162,18 @@ def _validate_approval_clarification_backtrace(
             f"final-report data.json: clarification `{row_id}` blocks approval "
             "and is linked, but the link resolves to no stage. `incremental-"
             "scope` reads the stage from a `P-Step-<stage>.<step>` / `P-Prep-"
-            "S<stage>-<kind>` plan-item id, or from a `Stage N` citation in the "
-            f"blocked coverage row's `coveredBy`. A `P-Req-*` / `P-Val-*` id "
-            "carries no stage number, so a row linked only that way must cite "
-            "the stage in `coveredBy`. A blocker whose blast radius resolves to "
-            "no stage cannot auto-narrow the next re-run; this report fails "
-            "rather than forcing a full re-run."
+            "S<stage>-<kind>` plan-item id, from `stageScope` / `stageRefs` on "
+            "the linked plan item or coverage row, or from a `Stage N` citation "
+            f"in the blocked coverage row's `coveredBy`. A `P-Req-*` / `P-Val-*` "
+            "id carries no stage number, so a row linked only that way must "
+            "carry `stageRefs` or cite the stage in `coveredBy`. A blocker "
+            "whose blast radius resolves to no stage cannot auto-narrow the "
+            "next re-run; this report fails rather than forcing a full re-run."
         )
 
 
 _RERUN_FLAG = "--answered-clarifications"
+_APPROVE_HINT = re.compile(r"--approve|\bapprov", re.IGNORECASE)
 
 
 def _next_step_texts(steps: object) -> list[str]:
@@ -6156,6 +6190,24 @@ def _next_step_texts(steps: object) -> list[str]:
     return texts
 
 
+def _has_blocks_approval_row(data: dict) -> bool:
+    return any(
+        isinstance(row, dict) and row.get("blocks") == "approval"
+        for row in data.get("clarificationItems") or []
+    )
+
+
+def _planning_gate_blocks_approval(data: dict) -> bool:
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        return False
+    verification = planning.get("planBodyVerification")
+    if not isinstance(verification, dict):
+        return False
+    gate = str(verification.get("gateResult") or "").strip().lower()
+    return gate in {"blocked-by-disagreement", "aborted-non-result"}
+
+
 def _validate_rerun_guidance(data: dict, failures: list[str]) -> None:
     """A report that withholds approval must say how to come back from it.
 
@@ -6168,10 +6220,7 @@ def _validate_rerun_guidance(data: dict, failures: list[str]) -> None:
     """
     if (data.get("header") or {}).get("taskType") != "implementation-planning":
         return
-    has_blocker = any(
-        isinstance(row, dict) and row.get("blocks") == "approval"
-        for row in data.get("clarificationItems") or []
-    )
+    has_blocker = _has_blocks_approval_row(data)
     if not has_blocker:
         return
     if any(_RERUN_FLAG in text for text in _next_step_texts(
@@ -6187,6 +6236,34 @@ def _validate_rerun_guidance(data: dict, failures: list[str]) -> None:
     )
 
 
+def _validate_approval_guidance(data: dict, failures: list[str]) -> None:
+    """승인 가능한 plan-ready 는 사용자에게 승인하라고 말해야 한다.
+
+    포인터가 implementation/ready 여도 승인은 사용자만 뒤집는다. 다음 단계
+    안내가 계획 재실행이면 승인 칸을 건너뛰고 같은 단계를 다시 돈다.
+    """
+    if (data.get("header") or {}).get("taskType") != "implementation-planning":
+        return
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict) or planning.get("outcome") != "plan-ready":
+        return
+    if _has_blocks_approval_row(data) or _planning_gate_blocks_approval(data):
+        return
+    if _report_already_approved(data):
+        return
+    if any(_APPROVE_HINT.search(text) for text in _next_step_texts(
+        data.get("recommendedNextSteps")
+    )):
+        return
+    failures.append(
+        "final-report data.json: this plan is ready for the user to approve, "
+        "but no `recommendedNextSteps` entry tells the reader to approve — "
+        "name `--approve` or the in-session wizard in a step's `text` or "
+        "one of its `commands`. Do not recommend another "
+        "implementation-planning run."
+    )
+
+
 def _validate_self_fix_grouping(data: dict, failures: list[str]) -> None:
     """A self-fix round must be instructed by cause, not as a flat item list.
 
@@ -8163,11 +8240,11 @@ def _validate_plan_body_clarification_matching(
     failures: list[str],
     accepted_item_ids: set[str] | None = None,
 ) -> None:
-    """H5 — every plan item that the recorded verdicts make `majority-disagree`
-    must point (via `clarificationId`) at an existing `blocks: approval`
-    clarification row. Closes the hole where a majority-disagree item blocks the
-    gate but no §1 Clarification row is raised, so the user never sees why
-    approval is withheld (implementation-planning.md self-review step 7).
+    """H5 — every plan item whose *gate class after stage scope* is
+    `majority-disagree` must point at an existing `blocks: approval`
+    clarification row. Observed / deferred / record items stay in `setAside`
+    and must not become a new C row — that is what grew the clarification
+    list while the next stage was already executable.
     """
     ip = data.get("implementationPlanning")
     if not isinstance(ip, dict):
@@ -8189,9 +8266,7 @@ def _validate_plan_body_clarification_matching(
     for item in pbv.get("planItems") or []:
         if not isinstance(item, dict):
             continue
-        if _classify_plan_item_gate(item) != "majority-disagree":
-            continue
-        if _is_dissent_downgraded(item, pbv, accepted):
+        if _plan_item_gate_class(item, pbv, accepted) != "majority-disagree":
             continue
         item_id = item.get("id") or "<unknown>"
         cids = _plan_item_clarification_ids(item)
@@ -8244,7 +8319,7 @@ def _validate_self_fix_before_clarification(data: dict, failures: list[str]) ->
     for item in pbv.get("planItems") or []:
         if not isinstance(item, dict):
             continue
-        if _classify_plan_item_gate(item) != "majority-disagree":
+        if _plan_item_gate_class(item, pbv, set()) != "majority-disagree":
             continue
         if _has_planner_fixable_majority(item):
             allowed = " / ".join(sorted(_SELF_FIX_EXHAUSTED_REASONS))