okstra 0.184.0 → 0.185.0

package/runtime/python/okstra_ctl/user_response.py

@@ -954,12 +954,15 @@ def list_awaiting_tasks(home: Path, project_id: str, limit: int) -> list[dict]:
 # `§x.y` is a full-reading-copy heading and is not a record coordinate.
 # `path.ext:line` is a source pointer the record does not define.
 _SECTION_REF_RE = re.compile(r"§[\d.]+|[A-Z]{1,4}-\d+|[\w./-]+\.\w+:\d+")
+_PATH_LINE_RE = re.compile(r"[\w./-]+\.\w+:\d+")
 _ID_TOKEN_RE = re.compile(r"^[A-Z]{1,4}-\d+$")
+_PLAN_ITEM_ID_RE = re.compile(r"^P-")
 _ROW_DEFINITION_KEYS = (
     "statement",
     "summary",
     "item",
     "title",
+    "subject",
     "check",
     "action",
     "evidence",
@@ -1992,6 +1995,138 @@ def _option_view(option: Mapping[str, Any], index: int) -> list[str]:
     ]
 
 
+def _option_probe_texts(options: list[Any]) -> list[str]:
+    texts: list[str] = []
+    for option in options:
+        if not isinstance(option, Mapping):
+            continue
+        texts.extend(
+            str(option.get(key) or "")
+            for key in ("answer", "rationale", "addedWork", "directionChange")
+        )
+    return texts
+
+
+def _row_probe_texts(row: Mapping[str, Any]) -> list[str]:
+    return [
+        str(row.get("statement") or ""),
+        str(row.get("expected_form") or ""),
+        *_option_probe_texts(list(row.get("options") or [])),
+    ]
+
+
+def _path_line_refs(*texts: str) -> list[str]:
+    found: list[str] = []
+    seen: set[str] = set()
+    for text in texts:
+        for match in _PATH_LINE_RE.findall(text or ""):
+            if match not in seen:
+                seen.add(match)
+                found.append(match)
+    return found
+
+
+def _why_asked(row: Mapping[str, Any]) -> str:
+    approval = row.get("approval_context") or {}
+    if not isinstance(approval, Mapping):
+        return "not stated in the report"
+    unblock = str(approval.get("unblockCondition") or "").strip()
+    if unblock:
+        return unblock
+    classification = str(approval.get("classification") or "").strip()
+    return classification or "not stated in the report"
+
+
+def _linked_plan_items(
+    record: dict[str, Any] | None, clarification_id: str
+) -> list[dict[str, str]]:
+    if record is None:
+        return []
+    linked: list[dict[str, str]] = []
+    seen: set[str] = set()
+
+    def walk(node: object) -> None:
+        if isinstance(node, dict):
+            row_id = node.get("id")
+            refs = node.get("clarificationRefs") or []
+            if (
+                isinstance(row_id, str)
+                and _PLAN_ITEM_ID_RE.match(row_id)
+                and isinstance(refs, list)
+                and clarification_id in refs
+                and row_id not in seen
+            ):
+                seen.add(row_id)
+                linked.append({
+                    "id": row_id,
+                    "definition": _row_definition(node) or "not stated in the report",
+                })
+            for value in node.values():
+                walk(value)
+        elif isinstance(node, list):
+            for item in node:
+                walk(item)
+
+    walk(record)
+    return linked
+
+
+def _format_ref_list(label: str, items: list[str]) -> list[str]:
+    if not items:
+        return [f"{label}: none"]
+    return [f"{label}:", *(f"- {item}" for item in items)]
+
+
+def _format_open_row_view(
+    row: Mapping[str, Any],
+    record: dict[str, Any] | None,
+    markdown_text: str,
+    response: UserResponseEntry | None,
+) -> list[str]:
+    item = row["item"]
+    probe = _row_probe_texts(row)
+    refs = sorted(set(_SECTION_REF_RE.findall(" ".join(probe))))
+    resolved = (
+        resolve_refs_from_record(record, refs)
+        if record is not None
+        else resolve_refs(markdown_text, refs)
+    )
+    lines = [
+        "",
+        f"[{item.row_id}]",
+        f"Kind: {item.kind}",
+        f"Blocks: {item.blocks}",
+        f"Report status: {item.status}",
+        f"Question: {row['statement']}",
+        f"Expected form: {row['expected_form']}",
+        f"Current response: {response.value if response else 'none'}",
+        f"Current disposition: {response.disposition if response else 'none'}",
+        f"Why asked: {_why_asked(row)}",
+        "Options:",
+    ]
+    approval = row.get("approval_context") or {}
+    if isinstance(approval, Mapping) and approval:
+        lines.extend([
+            f"Approval classification: {approval.get('classification', '')}",
+            f"Approval unblock condition: {approval.get('unblockCondition', '')}",
+            f"Approval recommended disposition: {approval.get('recommendedDisposition', '')}",
+        ])
+    for index, option in enumerate(row["options"], start=1):
+        lines.extend(_option_view(option, index))
+    linked = _linked_plan_items(record, item.row_id)
+    lines.extend(_format_ref_list(
+        "Linked plan items",
+        [f"{plan['id']}: {plan['definition']}" for plan in linked],
+    ))
+    lines.extend(_format_ref_list("Cited artifacts", _path_line_refs(*probe)))
+    lines.append("Context:")
+    lines.extend(
+        f"- {ref['ref']}: {ref['definition'] or 'not stated in the report'}"
+        for ref in resolved
+    )
+    return lines
+
+
 def format_show_view(report_path: Path, project_root: Path) -> str:
     context = _validate_owned_report_context(
         report_path, expected_project_root=project_root
@@ -1999,6 +2134,10 @@ def format_show_view(report_path: Path, project_root: Path) -> str:
     rows, record = _all_report_rows(context.report_path)
     state = _existing_sidecar_state(context.sidecar_path)
     current = {entry.response_id: entry for entry in state.entries}
+    markdown_text = (
+        "" if record is not None
+        else context.markdown_path.read_text(encoding="utf-8")
+    )
     lines = [
         "USER RESPONSE REPORT",
         f"Report: {context.report_path}",
@@ -2015,51 +2154,22 @@ def format_show_view(report_path: Path, project_root: Path) -> str:
     if candidates:
         lines.append("Plan option candidates:")
         for index, candidate in enumerate(candidates, start=1):
+            current_pick = (
+                state.plan_decision is not None
+                and state.plan_decision.implementation_option == candidate
+            )
             lines.extend([
                 f"Plan option {index}: {candidate}",
                 f"  Recommended: {'yes' if candidate == recommended_name else 'no'}",
-                "  Current decision: "
-                f"{'yes' if state.plan_decision and state.plan_decision.implementation_option == candidate else 'no'}",
+                f"  Current decision: {'yes' if current_pick else 'no'}",
             ])
     for row in rows:
         item = row["item"]
         if item.status not in {"open", "answered"} or item.row_id in current:
             continue
-        refs = sorted(set(_SECTION_REF_RE.findall(
-            row["statement"] + " " + row["expected_form"]
-        )))
-        resolved = (
-            resolve_refs_from_record(record, refs)
-            if record is not None
-            else resolve_refs(context.markdown_path.read_text(encoding="utf-8"), refs)
-        )
-        response = current.get(item.row_id)
-        lines.extend([
-            "",
-            f"[{item.row_id}]",
-            f"Kind: {item.kind}",
-            f"Blocks: {item.blocks}",
-            f"Report status: {item.status}",
-            f"Question: {row['statement']}",
-            f"Expected form: {row['expected_form']}",
-            f"Current response: {response.value if response else 'none'}",
-            f"Current disposition: {response.disposition if response else 'none'}",
-            "Options:",
-        ])
-        approval = row.get("approval_context") or {}
-        if approval:
-            lines.extend([
-                f"Approval classification: {approval.get('classification', '')}",
-                f"Approval unblock condition: {approval.get('unblockCondition', '')}",
-                f"Approval recommended disposition: {approval.get('recommendedDisposition', '')}",
-            ])
-        for index, option in enumerate(row["options"], start=1):
-            lines.extend(_option_view(option, index))
-        lines.append("Context:")
-        lines.extend(
-            f"- {ref['ref']}: {ref['definition'] or 'not stated in the report'}"
-            for ref in resolved
-        )
+        lines.extend(_format_open_row_view(
+            row, record, markdown_text, current.get(item.row_id),
+        ))
     return "\n".join(lines) + "\n"
 
 

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,104 @@
+---
+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:recipient:body`.
+
+## Step 3: Next action
+
+Ask: send, inbox, log, ack, or done.
+
+### Send
+
+1. Run `okstra chat members --room <room>`.
+2. Pick the recipient from `all` plus those names. 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.
+
+### Log
+
+```bash
+okstra chat log --room <room> --as <display>
+```
+
+The whole room, including messages not addressed to you.
+
+### Ack
+
+After unread, mark the last id the user has read:
+
+```bash
+okstra chat ack --room <room> --as <display> --through <id>
+```
+
+## 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