okstra 0.186.0 → 0.186.2

package/docs/architecture.md

@@ -887,7 +887,7 @@ Entry points:
 - Python routing references: `scripts/okstra_ctl/report_views.py` owns the version split; `scripts/okstra_ctl/report_html/router.py` maps all v2 task types to dedicated view-model builders and templates. The HTML JavaScript response serializer remains byte-identical to Python `serialize_user_response`.
 - CLI: `scripts/okstra-render-report-views.py <final-report.data.json|final-report.md>` or delegated Node wrapper `bin/okstra render-views <path>`.
 - Validation: `validators/validate-report-views.py` checks schema/source/template digests, required human fields, form controls, external assets, SVG/table ID parity, and Response ID parity. The v2 renderer rejects an unknown task type instead of falling back to a generic page.
-- User-response sidecar schema source of truth: `templates/reports/user-response.template.md`. The in-session skill reads `okstra user-response show-view`, then the cited `path:line` artifacts and linked plan items that view lists, before asking. The recorded answer still comes from `options[]` via `--option-number`. Task pick, each clarification, and the record confirmation use the current host's native question tool from the relay `native-single` mapping (`AskUserQuestion`, `ask_user_question`, or `request_user_input`). A numbered list is only the fallback when that tool is missing or the option count misses `nativeLimits`.
+- User-response sidecar schema source of truth: `templates/reports/user-response.template.md`. The in-session skill reads `okstra user-response show-view`, then the cited `path:line` artifacts and linked plan items that view lists, before asking. The recorded answer still comes from `options[]` via `--option-number`. Task pick, each clarification, and the record confirmation use the current host's native question tool from the relay `native-single` mapping (`AskUserQuestion`, `ask_user_question`, or `request_user_input`). The picker shows those choices only — it does not append `Enter directly`; custom text uses the host free-text row. A numbered list is only the fallback when that tool is missing or the option count misses `nativeLimits`.
 - In-run user confirmation before an approval blocker follows the same briefing order and the same host picker: the lead investigates cited plan items, worker findings, and files, then asks through the adapter `prompt_user` mapping (`prompts/lead/okstra-lead-contract.md`).
 
 Generating a view never modifies the original final-report MD.

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

@@ -221,7 +221,7 @@ Inform the user on one line.
 Took over as Okstra lead (`<host-runtime>`) for `<taskKey>` (`<task-type>`). Run dir: `<RUN_DIR_RELATIVE_PATH>`. Beginning Phase 1 (context loading).
 ```
 
-For a single-element chain, the end of Step 6 is the end of the run. Step 7 below applies only when the `chain-stages` CSV has 2 or more elements. After an `implementation-planning` run, if `workflow.awaitingApproval` is true, tell the user to approve the plan; do not start another planning run. If the pointer is `blocked`, send the user to `okstra-user-response` first.
+For a single-element chain, the end of Step 6 is the end of the run. Step 7 below applies only when the `chain-stages` CSV has 2 or more elements. When the run is over, close with the user's next action — one command they can run now. A prohibition is not a next action. After `implementation-planning`: open or answered approval blockers → `/okstra-user-response`; awaiting approval → `/okstra-run` → `implementation` or `--approve` (do not start another planning run); `validate-run` failed → one-line cause then `/okstra-run` or `/okstra-inspect recap`; pointer `ready` → `/okstra-run` for that phase.
 
 ## implementation unattended chaining (chain-stages)
 

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

@@ -27,8 +27,8 @@ The legacy `list` and `show` JSON commands remain for automation compatibility.
 ## Flow
 
 1. Run `okstra preflight --runtime <host-runtime>` for the current harness. On `Okstra preflight: failed`, show `Reason` and `Recovery`, then stop. On `Okstra preflight: ready`, carry `Project root`, `Project ID`, `Runtime`, and `Relay contract`, then run `okstra paths --field home`.
-2. Read the relay `Wizard interaction relay` JSON. When `native-single` is available and the option count fits `nativeLimits`, call `interactions.native-single.function` (`AskUserQuestion` / `ask_user_question` / `request_user_input` from that field). Do not print a numbered list in chat while the native tool is available. Otherwise render a numbered Markdown list. Do not substitute one host function name for another.
-3. Select a task from `list-view` through that host picker.
+2. Read the relay `Wizard interaction relay` JSON. When `native-single` is available and the option count fits `nativeLimits`, call `interactions.native-single.function` (`AskUserQuestion` / `ask_user_question` / `request_user_input` from that field). Do not print a numbered list in chat while the native tool is available. Otherwise render a numbered Markdown list. Do not substitute one host function name for another. Pass only the choices this step already owns. Do not append `Enter directly`. Claude Other, Grok `z`, and Codex's free-form row are `Enters an answer`; on a numbered list, so is a next message that is not a listed label or its 1-based number. Do not ask a second question for the custom value.
+3. Select a task from `list-view` through that host picker. A host free-text row or unmatched next message is the report path or task key.
 4. Read only `show-view --report <reportPath> --project-root <projectRoot>` for report facts. The view also prints `Why asked`, `Linked plan items`, and `Cited artifacts`.
 5. Read every cited `path:line` under the project root and every linked plan-item definition before asking. Do not search beyond that list. Investigation explains; it never changes `options[]`.
 6. Ask one open clarification at a time in the user's language through the host picker. The question body is why, what is already decided, the fork, and what stays blocked. Do not lead with `Kind`, `Blocks`, `Expected form`, or `C-NNN`. Keep the row id in parentheses at the end.

package/docs/project-structure-overview.md

@@ -277,6 +277,7 @@ Important modules:
 | `report_assembly.py` | Validates the role-owned report inputs and publishes the contract 3.0 record once (assembled in a temp file, then atomically promoted); a bad input aborts with owner / artifact path / field path / reason and preserves the existing `data.json` |
 | `report_projections.py` | Pure projections turning role-owned execution inputs (agent activity, execution status, convergence, design, token usage) into canonical final-report fragments |
 | `report_narrative.py` | Lossless read/write contract for the report-writer-owned narrative Markdown (`report-narrative-<task-type>-<seq>.md`) — the only artifact the report-writer authors under contract 3.0 |
+| `report_synthesis_packet.py` | Builds the frozen, read-only synthesis input packet handed to the report-writer — collects each source's label / owner / path / content digest into `report-writer-synthesis-packet-<task-type>-<seq>.{json,md}`, materialized at dispatch by `initial_prompt_materialization.py` so the writer synthesizes from a byte-stable snapshot. `report_assembly.py` calls `verify_report_synthesis_packet_sources` at publish time so a drifted source aborts the record; schema is `schemas/report-synthesis-packet-v1.0.schema.json` |
 | `approval_decisions.py` | Lead-owned approval-decision input ledger — `disposition` (`select`/`accept-risk`/`request-revision`/`reject`), reach, scope effect, and classification invariants (`correctness-critical`/`noncritical-dissent`/`user-decision`) |
 | `design_snapshot.py` | Builds the design-surface-detector-owned snapshot from the report narrative — reproducible design surfaces plus conservative `PREP-NNN` preparation items (delegates surface detection to `design_surfaces.py`) |
 | `report_markdown.py` | Schema-ordered Markdown serialisation of a data.json subtree for the full reading copy — headings, tables for uniform row sets, prose for narrative fields; field order read from the schema, not from the mapping |
@@ -696,4 +697,4 @@ Clarifications now live in the unified `## 1. Clarification Items` table. Deprec
 
 ---
 
-*Updated: 2026-08-23 · Source of truth checked against `package.json`, `bin/okstra`, `src/cli-registry.mts`, `src/lib/skill-catalog.mts`, `tools/build.mjs`, `scripts/`, `skills/`, `agents/`, `templates/`, `schemas/`, `validators/`, and tests.*
+*Updated: 2026-08-24 · Source of truth checked against `package.json`, `bin/okstra`, `src/cli-registry.mts`, `src/lib/skill-catalog.mts`, `tools/build.mjs`, `scripts/`, `skills/`, `agents/`, `templates/`, `schemas/`, `validators/`, and tests.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.186.0",
+  "version": "0.186.2",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.186.0",
-  "builtAt": "2026-08-23T16:32:26.938Z",
+  "package": "0.186.2",
+  "builtAt": "2026-08-24T02:07:41.323Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -425,7 +425,19 @@ jq -s 'group_by(.errorType) | map({type: .[0].errorType, count: length})' <runDi
 
 The errors log is informational. Its presence/absence does not affect the final verdict. Do not block report writing on it.
 
-After persistence, reply briefly in the resolved Report Language with: completion status, the human report path, the report record path, team-state path, validator result, resume command path, any remaining blocker. For `implementation-planning` that left `workflow.awaitingApproval` true, the first sentence after the task identity tells the user to approve this plan (`okstra-run` → `implementation`, which asks `approve_plan_confirm`, or `--approve`) and does not propose another planning run. For a `blocked` pointer after planning, the first sentence names the open `C-NNN` ids and sends the user to `okstra-user-response`; do not start implementation and do not re-run planning until those answers exist. **Lead this reply with the run's task identity** — state `<task-group>/<task-id>` (or the full `taskKey`) first, so the reader knows which task the reply is about. **Every run-artifact path in this reply MUST be task-qualified** — report the human report as `.okstra/tasks/<task-group>/<task-id>/runs/<task-type>/reports/final-report-<task-type>-<seq>.html` rooted at the task bundle, NOT the bare `runs/<task-type>/reports/...` form (byte-for-byte identical across every task of the same task-type, so it cannot identify the task). Under that, cite the report record (`.data.json`) and one line to render the full reading copy: `okstra render-final-report <task-qualified data.json>`. The same task-qualified rule applies to the team-state path, resume command path, and any other run-artifact path this reply cites.
+After persistence, reply briefly in the resolved Report Language. **Lead this reply with the run's task identity** — state `<task-group>/<task-id>` (or the full `taskKey`) first. Then: completion status, the task-qualified human report path, the report record path, validator result, any remaining blocker. **Close with the user's next action** — one command they can run now. A prohibition (`do not start implementation`) is not a next action. A status dump is not a close.
+
+Pick the next action from this table; the first matching row wins:
+
+- Open or answered `blocks: approval` rows → `/okstra-user-response` (name the `C-NNN` ids). Do not start implementation and do not re-run planning until those answers exist.
+- `workflow.awaitingApproval` is true → `/okstra-run` → `implementation` (asks `approve_plan_confirm`) or `--approve`. Do not propose another planning run.
+- Phase 7 `validate-run` failed → one line naming the blocking cause, then `/okstra-run` to re-run this phase with the recorded sidecar, or `/okstra-inspect recap` if the resume flags are unknown.
+- Pointer `status: ready` → `/okstra-run` for that `phase`.
+- Otherwise → `/okstra-inspect status` for this task.
+
+When the host native picker is available and two of those rows could apply, ask with that picker (recommended first). Do not end the turn after the status dump.
+
+**Every run-artifact path in this reply MUST be task-qualified** — report the human report as `.okstra/tasks/<task-group>/<task-id>/runs/<task-type>/reports/final-report-<task-type>-<seq>.html` rooted at the task bundle, NOT the bare `runs/<task-type>/reports/...` form (byte-for-byte identical across every task of the same task-type, so it cannot identify the task). Under that, cite the report record (`.data.json`) and one line to render the full reading copy: `okstra render-final-report <task-qualified data.json>`. The same task-qualified rule applies to the team-state path, resume command path, and any other run-artifact path this reply cites.
 
 ## Run-scoped worker-resource lifecycle
 

package/runtime/prompts/profiles/implementation-planning.md

@@ -195,7 +195,7 @@ roles:
   - dependency / migration risk assessment (ordering constraints, data backfills, feature-flag prerequisites, repo-internal sequencing)
   - **Cross-Project Dependencies (conditionally required):** when the plan depends on work in another project / repo / published package, add (a) a `kind: cross-project` DM row to `dependencyMigrationRisk`, and (b) a matching `XP-NNN` row to `crossProjectDependencies`. An upstream-precondition row must have concrete `requiredWork` / `verificationSignal` / `howToStart` — `validators/validate-run.py` enforces that a DM `cross-project` ⇒ at least one `direction: upstream-precondition` XP row, and the schema enforces non-empty row fields. A cross-project dependency is recorded as this structured precondition, not as a soft Recommended Next Step. A single-project plan uses an empty array.
   - **recommendedNextSteps policy:** keep the substance of cross-project preconditions/carries in `crossProjectDependencies`, and put in `§3 Recommended Next Steps` only a pointer to that section (`§5.4 Cross-Project Dependencies`) — no double recording.
-  - **Resuming from an approval blocker (BLOCKING).** When this report carries any `blocks: approval` clarification, one `recommendedNextSteps` entry MUST name the `--answered-clarifications` re-run, in its `text` or in one of its `commands`. The reader of the report is the person who has to act, and until now the mechanics of resuming lived only in the lead prompt — which is read after the next run has already started. Point them at `okstra recap assemble`, which prints the answered ids, the exact flag value, the sidecar paths, and whether the re-verification would fall back to full. Do not restate those values here: they are unknown while you write, because the user has not answered yet. The first human action is answering those rows (`okstra-user-response`); do not tell the reader to start another planning run before the answers exist. **Enforced:** `validators/validate-run.py` `_validate_rerun_guidance`.
+  - **Resuming from an approval blocker (BLOCKING).** When this report carries an unresolved (`open` or `answered`) `blocks: approval` clarification, `recommendedNextSteps[0]` MUST be a command the reader can run now: `/okstra-user-response`, and the `--answered-clarifications` re-run in that step's `text` or `commands`. Do not write "The Okstra lead will …" as the first step. Point them at `okstra recap assemble`, which prints the answered ids, the exact flag value, the sidecar paths, and whether the re-verification would fall back to full. Do not restate those values here: they are unknown while you write, because the user has not answered yet. Do not tell the reader to start another planning run before the answers exist. **Enforced:** `validators/validate-run.py` `_validate_rerun_guidance`.
   - **Asking for approval (BLOCKING).** When `outcome` is `plan-ready`, the gate is `passed` or `passed-with-dissent`, and no `blocks: approval` row is open, one `recommendedNextSteps` entry MUST tell the reader to approve (`--approve` or the in-session wizard). Do not recommend another `implementation-planning` run. **Enforced:** `validators/validate-run.py` `_validate_approval_guidance`.
   - validation checklist (pre / mid / post) — each item is an exact command or observable outcome
   - rollback strategy — exact revert path (commits, flags, migrations) and the signal that triggers rollback

package/runtime/python/okstra_ctl/design_surfaces.py

@@ -181,6 +181,84 @@ def _stage_rows(planning: Mapping[str, Any]) -> dict[int, Mapping[str, Any]]:
 
 
 _LINE_RANGE_SUFFIX = re.compile(r":\d+(?:-\d+)?$")
+_PAREN_SUFFIX = re.compile(r"\s*\([^)]*\)\s*$")
+
+
+def _split_declared_paths(raw: str) -> list[str]:
+    """쉼표·줄바꿈으로 이어진 경로를 파일 단위로 나눈다. `{a,b}` 안 쉼표는 유지.
+
+    `fileStructure.path` 는 원래 열 수 있는 경로 하나인데, 계획이 여러 파일을
+    한 칸에 이어 쓰면 추출기가 그 문자열 전체를 한 경로로 보고 스테이지 매핑에
+    실패한다.
+    """
+    parts: list[str] = []
+    buf: list[str] = []
+    depth = 0
+    for char in raw:
+        if char == "{":
+            depth += 1
+            buf.append(char)
+        elif char == "}":
+            depth = max(0, depth - 1)
+            buf.append(char)
+        elif char in ",\n" and depth == 0:
+            token = "".join(buf).strip()
+            if token:
+                parts.append(token)
+            buf = []
+        else:
+            buf.append(char)
+    token = "".join(buf).strip()
+    if token:
+        parts.append(token)
+    return parts
+
+
+def _step_files_cells(step: Mapping[str, Any]) -> list[str]:
+    raw = step.get("files")
+    if isinstance(raw, list):
+        return [_normalise(item) for item in raw if item]
+    text = _normalise(raw)
+    return [text] if text else []
+
+
+def _files_cell_tokens(cell: str) -> list[str]:
+    tokens: list[str] = []
+    for part in _split_declared_paths(cell) or [cell]:
+        token = _LINE_RANGE_SUFFIX.sub("", part)
+        token = _PAREN_SUFFIX.sub("", token).strip()
+        if token:
+            tokens.append(token)
+    return tokens
+
+
+def _cell_covers_path(cell: str, path: str) -> bool:
+    path_pattern = rf"(?<![\w./@-]){re.escape(path)}(?![\w./@-])"
+    if re.search(path_pattern, cell) is not None:
+        return True
+    for token in _files_cell_tokens(cell):
+        if token == path:
+            return True
+        if "*" in token and fnmatch.fnmatch(path, token):
+            return True
+    return False
+
+
+def _stages_touching_path(
+    path: str,
+    stages: Mapping[int, Mapping[str, Any]],
+) -> list[int]:
+    hits: list[int] = []
+    for stage_number, stage in stages.items():
+        cells = [
+            cell
+            for step in stage.get("stepwiseExecution") or []
+            if isinstance(step, Mapping)
+            for cell in _step_files_cells(step)
+        ]
+        if any(_cell_covers_path(cell, path) for cell in cells):
+            hits.append(stage_number)
+    return hits
 
 
 def _stages_for_selected_path(
@@ -200,21 +278,27 @@ def _stages_for_selected_path(
     Zero stages is still an error: the recommended option declares a file that
     no step creates or edits.
     """
-    normalised = _LINE_RANGE_SUFFIX.sub("", _normalise(path))
-    path_pattern = rf"(?<![\w./@-]){re.escape(normalised)}(?![\w./@-])"
-    matched = []
-    for stage_number, stage in stages.items():
-        files = [
-            _normalise(step.get("files"))
-            for step in stage.get("stepwiseExecution") or []
-            if isinstance(step, Mapping)
-        ]
-        if any(re.search(path_pattern, cell) is not None for cell in files):
-            matched.append(stage_number)
-    if not matched:
+    declared = [
+        _LINE_RANGE_SUFFIX.sub("", _normalise(part))
+        for part in (_split_declared_paths(path) or [path])
+    ]
+    declared = [part for part in declared if part]
+    if not declared:
         raise DesignSurfaceError(
             f"selected option path {path!r} is not mapped to a stage"
         )
+    matched: list[int] = []
+    seen: set[int] = set()
+    for part in declared:
+        hits = _stages_touching_path(part, stages)
+        if not hits:
+            raise DesignSurfaceError(
+                f"selected option path {part!r} is not mapped to a stage"
+            )
+        for stage_number in hits:
+            if stage_number not in seen:
+                seen.add(stage_number)
+                matched.append(stage_number)
     return matched
 
 
@@ -243,12 +327,13 @@ def detect_design_surfaces(
             continue
         path = str(row.get("path") or "")
         for stage_number in _stages_for_selected_path(path, stages):
-            for kind, evidence in _matching_rule_evidence(
-                step=None,
-                field="files",
-                value=path,
-            ):
-                grouped.setdefault((stage_number, kind), []).append(evidence)
+            for declared in _split_declared_paths(path) or [path]:
+                for kind, evidence in _matching_rule_evidence(
+                    step=None,
+                    field="files",
+                    value=declared,
+                ):
+                    grouped.setdefault((stage_number, kind), []).append(evidence)
     rule_order = {rule.kind: index for index, rule in enumerate(RULES)}
     return [
         DesignSurfaceTrigger(stage, kind, tuple(grouped[(stage, kind)]))

package/runtime/python/okstra_ctl/worker_prompt_body.py

@@ -6,25 +6,14 @@ from typing import Any, Mapping, Sequence
 from .worker_prompt_policy import PromptPlan
 
 
-_ANALYSIS_WORKER_LABELS = {
-    "claude": "Claude worker",
-    "codex": "Codex worker",
-    "antigravity": "Antigravity worker",
-}
-
-
 def analysis_worker_label(worker_id: str) -> str:
     """The role label this worker's prompt body is titled with.
 
-    The map above only supplies display capitalization for the three providers
-    that predate it; every other worker id (`grok`, `kimi`, a user-installed
-    adapter) takes the id itself. Both branches are identity deltas the equality
-    group must normalize away, so `worker_prompt_contract` erases exactly what
-    this function returns rather than restating the map — an enumeration that
-    covered only the map's keys let `# grok worker Dispatch` through and failed
-    every roster carrying grok or kimi before publication.
+    The label is `{worker_id} worker` for every id. A three-provider display
+    map made grok/kimi a second branch, and any consumer that restated the map
+    treated those ids as unnamed.
     """
-    return _ANALYSIS_WORKER_LABELS.get(worker_id, f"{worker_id} worker")
+    return f"{worker_id} worker"
 
 
 def analysis_prompt_body(

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -159,11 +159,8 @@ def _worker_label_pattern(worker_ids: Iterable[str]) -> re.Pattern[str] | None:
     """Match the role label the body renderer titled each compared worker with.
 
     Built from `analysis_worker_label`, the same function that writes the label,
-    so a provider outside its display map (`grok`, `kimi`) is covered as it
-    comes. Restating the map here is what forked the roster: the enumeration
-    named only Claude / Codex / Antigravity, `# grok worker Dispatch` survived
-    normalization, and every run rostering grok or kimi failed the equality group
-    before publication with no prompt defect to fix.
+    so every worker id in the comparison group is covered. Restating a
+    three-provider list here is what forked the roster.
     """
     labels = sorted(
         {

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

@@ -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 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.
+- 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. When the lead (or this skill, after the lead returns) reports the run over, close with the user's next action — one command they can run now. A prohibition is not a next action. After `implementation-planning`, read `workflow.awaitingApproval` and the next-phase pointer from the task manifest. Open or answered `blocks: approval` rows → `/okstra-user-response`. Awaiting approval → `/okstra-run` → `implementation` or `--approve` (do not start another planning run). Phase 7 `validate-run` failed → one-line cause, then `/okstra-run` to re-run this phase with the sidecar, or `/okstra-inspect recap`. Pointer `status: ready` → `/okstra-run` for that phase. Otherwise `/okstra-inspect status`.

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

@@ -59,6 +59,8 @@ Read the absolute path in the fixed `Relay contract` line. In that file, take th
 - 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.
 
+Pass only the choices this step already owns — the `list-view` rows, the report `options[]`, or the two confirmation labels. Do not append `Enter directly`. Claude Other, Grok `z`, and Codex's free-form row already collect a custom answer; that row is `Enters an answer`. When native-single is unavailable, a next message that is not a listed label or its 1-based number is the same `Enters an answer`. Do not ask a second question for the custom value.
+
 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
@@ -69,7 +71,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 through the host picker. 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. A host free-text row or unmatched next message is the report path or task key.
 
 ## Step 2: Read the fixed report view
 
@@ -79,7 +81,7 @@ 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, 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`.
+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.
 
 Contract 3.0 options also expose `reach` and `scopeEffects`. Contract 3.0 approval-blocking rows expose `approvalContext`.
 

package/runtime/templates/reports/html/assets/base.css

@@ -133,27 +133,34 @@ button[data-action="export-user-response"]:hover { background: color-mix(in srgb
   display: flex;
   flex-direction: column;
   align-items: flex-end;
+  gap: .4rem;
 }
-.back-to-top {
+.back-to-top-actions { display: flex; gap: .4rem; }
+.back-to-top,
+.back-to-top-toggle {
   padding: .55rem .9rem;
   border-radius: 8px;
-  border: 1px solid color-mix(in srgb, CanvasText 28%, transparent);
-  background: color-mix(in srgb, Canvas 92%, CanvasText 8%);
+  border: 1px solid color-mix(in srgb, CanvasText 40%, transparent);
+  background: Canvas;
   color: CanvasText;
   text-decoration: none;
   font: inherit;
   font-size: .9rem;
-  box-shadow: 0 2px 8px color-mix(in srgb, CanvasText 18%, transparent);
+  font-weight: 600;
+  cursor: pointer;
+  box-shadow: 0 2px 10px color-mix(in srgb, CanvasText 28%, transparent);
 }
-.back-to-top:hover { background: color-mix(in srgb, CanvasText 12%, Canvas); }
-.back-to-top:focus-visible { outline: 2px solid Highlight; outline-offset: 2px; }
+.back-to-top:hover,
+.back-to-top-toggle:hover { background: color-mix(in srgb, CanvasText 12%, Canvas); }
+.back-to-top:focus-visible,
+.back-to-top-toggle:focus-visible { outline: 2px solid Highlight; outline-offset: 2px; }
 .back-to-top-index {
   display: none;
   box-sizing: border-box;
   width: min(22rem, calc(100vw - 2.4rem));
   max-height: min(70vh, 32rem);
   overflow: auto;
-  margin: 0 0 .4rem;
+  margin: 0;
   padding: .8rem 1rem;
   border-radius: 12px;
   border: 1px solid color-mix(in srgb, CanvasText 14%, transparent);
@@ -163,10 +170,13 @@ button[data-action="export-user-response"]:hover { background: color-mix(in srgb
 .back-to-top-index ol { margin: 0; padding-left: 1.2rem; }
 .back-to-top-index li { margin: .25em 0; }
 .back-to-top-index a { color: inherit; }
+.back-to-top-wrap.is-open .back-to-top-index { display: block; }
 @media (hover: hover) {
-  .back-to-top-wrap:hover .back-to-top-index,
-  .back-to-top-wrap:focus-within .back-to-top-index { display: block; }
+  .back-to-top-wrap:hover .back-to-top-index { display: block; }
 }
+.clarification-option { cursor: pointer; border-radius: 10px; padding: .6rem .7rem; }
+.clarification-option.is-selected { background: color-mix(in srgb, Highlight 12%, Canvas); }
+.clarification-item.is-closed .clarification-option { cursor: default; }
 /* A seven-column table needs 42em of floor, more than a phone can give. */
 @media (max-width: 640px) { section { padding: 1rem; } .visualization { display: none; } th, td { min-width: 4.5em; } nav.report-index ol { columns: 1; } }
 @media print { .skip-link, .back-to-top-wrap, script { display: none !important; } body { color: #000; background: #fff; } section { break-inside: avoid; border-color: #bbb; } .visualization-fallback { display: table; } }

package/runtime/templates/reports/html/assets/base.js

@@ -2,4 +2,25 @@
   "use strict";
 
   document.documentElement.classList.add("js-enabled");
+
+  // 목차는 hover 만으로는 안 열린다. 클릭으로 연다.
+  var wrap = document.querySelector(".back-to-top-wrap");
+  var toggle = wrap && wrap.querySelector(".back-to-top-toggle");
+  if (!wrap || !toggle) return;
+
+  function setOpen(open) {
+    wrap.classList.toggle("is-open", open);
+    toggle.setAttribute("aria-expanded", open ? "true" : "false");
+  }
+
+  toggle.addEventListener("click", function (event) {
+    event.stopPropagation();
+    setOpen(!wrap.classList.contains("is-open"));
+  });
+  document.addEventListener("click", function (event) {
+    if (!wrap.contains(event.target)) setOpen(false);
+  });
+  document.addEventListener("keydown", function (event) {
+    if (event.key === "Escape") setOpen(false);
+  });
 })();

package/runtime/templates/reports/html/base.template.html

@@ -115,8 +115,11 @@
     <pre id="user-response-output" aria-live="polite"></pre>
   </footer>{% endif %}
   <div class="back-to-top-wrap">
-    <nav class="back-to-top-index" aria-label="{{ t('base.contents') }}"><!--report-index-items--></nav>
-    <a class="back-to-top" href="#top">{{ t('base.back-to-top') }}</a>
+    <nav class="back-to-top-index" id="back-to-top-index" aria-label="{{ t('base.contents') }}"><!--report-index-items--></nav>
+    <div class="back-to-top-actions">
+      <button type="button" class="back-to-top-toggle" aria-expanded="false" aria-controls="back-to-top-index">{{ t('base.contents') }}</button>
+      <a class="back-to-top" href="#top">{{ t('base.back-to-top') }}</a>
+    </div>
   </div>
   <script id="run-meta" type="application/json">{{ {
     "task-key": runMeta.task_key,

package/runtime/templates/reports/html/i18n/en.json

@@ -159,6 +159,7 @@
       "count-answered-questions": "{count} answered questions",
       "your-answer-to-id": "Your answer to {id}",
       "choose-one": "Choose one",
+      "other-answer": "Other (type your own)",
       "recommended": "Recommended",
       "scope-impact": "Scope",
       "added-work": "Added work",

package/runtime/templates/reports/html/i18n/ko.json

@@ -159,6 +159,7 @@
       "count-answered-questions": "답한 질문 {count}건",
       "your-answer-to-id": "{id}에 대한 답변",
       "choose-one": "하나를 선택하세요",
+      "other-answer": "기타 (직접 입력)",
       "recommended": "권장",
       "scope-impact": "범위",
       "added-work": "추가 작업",

package/runtime/templates/reports/html/macros/forms.html

@@ -78,7 +78,7 @@
   {% if options %}
   <ol class="clarification-options">
     {% for option in options %}
-    <li class="clarification-option{% if option.role == 'recommended' %} is-recommended{% endif %}">
+    <li class="clarification-option{% if option.role == 'recommended' %} is-recommended{% endif %}" data-option-value="{{ option.answer }}">
       <p class="clarification-option-answer">{{ option.answer }}{% if option.role == 'recommended' %} <span class="badge">{{ t('macros.forms.recommended') }}</span>{% endif %}</p>
       {% if option.disposition | default(None) %}<p class="clarification-option-disposition"><code>{{ option.disposition }}</code></p>{% endif %}
       <p class="clarification-option-rationale">{{ option.rationale }}</p>
@@ -92,11 +92,16 @@
   </ol>
   {% endif %}
   <label for="response-{{ row.id }}">{{ t('macros.forms.your-answer-to-id') | replace('{id}', row.id) }}</label>
-  {% if row.kind == 'decision' and approval_context and options %}
+  {% if options %}
+  {% set pick = namespace(has_other=false, current=row.userInput | default('')) %}
+  {% for option in options %}{% if option.answer == '__other__' %}{% set pick.has_other = true %}{% endif %}{% endfor %}
+  {% set is_custom = pick.current and pick.current not in (options | map(attribute='answer') | list) %}
   <select id="response-{{ row.id }}" data-response-id="{{ row.id }}"{% if is_closed %} disabled{% endif %}>
     <option value="">{{ t('macros.forms.choose-one') }}</option>
-    {% for option in options %}<option value="{{ option.answer }}" data-disposition="{{ option.disposition | default('') }}"{% if option.role == 'recommended' %} data-recommended="true"{% endif %}{% if row.userInput | default('') == option.answer %} selected{% endif %}>{{ option.answer }}</option>{% endfor %}
+    {% for option in options %}<option value="{{ option.answer }}" data-disposition="{{ option.disposition | default('') }}"{% if option.role == 'recommended' %} data-recommended="true"{% endif %}{% if pick.current == option.answer %} selected{% endif %}>{{ option.answer }}</option>{% endfor %}
+    {% if not pick.has_other %}<option value="__other__"{% if is_custom %} selected{% endif %}>{{ t('macros.forms.other-answer') }}</option>{% endif %}
   </select>
+  {% if not pick.has_other %}<textarea data-other-for="{{ row.id }}" rows="2"{% if is_closed %} disabled{% endif %}{% if not is_custom %} hidden{% endif %}>{% if is_custom %}{{ pick.current }}{% endif %}</textarea>{% endif %}
   {% else %}
   <textarea id="response-{{ row.id }}" data-response-id="{{ row.id }}" rows="4"{% if is_closed %} disabled{% endif %}>{{ row.userInput | default('') }}</textarea>
   {% endif %}

package/runtime/templates/reports/report.js

@@ -274,6 +274,38 @@
     }
   }
 
+  // 선택 카드는 보여 주기만 하면 고른 것처럼 보이지만 값이 안 실린다.
+  // 카드를 누르면 같은 칸의 select 를 맞춘다.
+  function bindOptionCardPicks() {
+    var articles = document.querySelectorAll("article[data-response-id]");
+    for (var i = 0; i < articles.length; i++) {
+      (function (article) {
+        var sel = article.querySelector("select[data-response-id]");
+        if (!sel) return;
+        var cards = article.querySelectorAll(".clarification-option[data-option-value]");
+        var sync = function () {
+          for (var c = 0; c < cards.length; c++) {
+            cards[c].classList.toggle(
+              "is-selected",
+              cards[c].getAttribute("data-option-value") === sel.value
+            );
+          }
+        };
+        for (var c = 0; c < cards.length; c++) {
+          cards[c].addEventListener("click", function (event) {
+            if (sel.disabled) return;
+            if (event.target.closest && event.target.closest("a")) return;
+            sel.value = event.currentTarget.getAttribute("data-option-value") || "";
+            sel.dispatchEvent(new Event("change"));
+            sync();
+          });
+        }
+        sel.addEventListener("change", sync);
+        sync();
+      })(articles[i]);
+    }
+  }
+
   function quotedReviewField(label, value) {
     var cleaned = trimMultiline(value);
     if (!cleaned) return "- " + label + ":\n";
@@ -547,6 +579,7 @@
       setReaderMode("action");
     }
     bindOtherInputToggle();
+    bindOptionCardPicks();
   }
 
   if (typeof window !== "undefined") {

package/runtime/validators/validate-run.py

@@ -4117,6 +4117,77 @@ def _state_classification(item: dict, gate_class: str) -> str:
     return "dissent-isolated" if dissenting == 1 else "partial-consensus"
 
 
+def _clarification_resolution(row: dict, context: dict) -> dict | None:
+    """계약 3.0 은 행의 `resolution`, 2.0 은 `approvalContext.resolution`."""
+    for candidate in (row.get("resolution"), context.get("resolution")):
+        if isinstance(candidate, dict):
+            return candidate
+    return None
+
+
+def _clarification_ids_on_activity(activity: dict) -> set[str]:
+    refs: set[str] = set()
+    for key in ("clarificationRefs", "evidenceRefs"):
+        for value in activity.get(key) or []:
+            if isinstance(value, str) and _APPROVAL_CLARIFICATION_ID_RE.fullmatch(value):
+                refs.add(value)
+    return refs
+
+
+def _plan_item_ids_for_clarification(
+    row: dict, context: dict, data: dict,
+) -> list[str]:
+    """이 C 행이 가리키는 계획 항목.
+
+    계약 3.0 `approvalContext` 는 `planItemIds` 를 갖지 않는다. 활동
+    `evidenceRefs` / `clarificationRefs` 와 `planItems[].clarificationRefs` 가
+    역추적이다. 이 C 만 인용한 활동을 묶음 활동보다 앞세운다.
+    """
+    linked = [
+        item_id
+        for item_id in (context.get("planItemIds") or [])
+        if isinstance(item_id, str) and item_id
+    ]
+    if linked:
+        return linked
+    row_id = str(row.get("id") or "")
+    if not row_id:
+        return []
+    singleton: list[str] = []
+    bulk: list[str] = []
+    for activity in data.get("agentActivity") or []:
+        if not isinstance(activity, dict):
+            continue
+        refs = _clarification_ids_on_activity(activity)
+        if row_id not in refs:
+            continue
+        ids = [
+            item_id
+            for item_id in (activity.get("planItemIds") or [])
+            if isinstance(item_id, str) and item_id
+        ]
+        if refs == {row_id}:
+            singleton.extend(ids)
+        else:
+            bulk.extend(ids)
+    if singleton or bulk:
+        return singleton or bulk
+    items = (
+        ((data.get("implementationPlanning") or {}).get("planBodyVerification")
+         or {}).get("planItems") or []
+    )
+    return [
+        str(item.get("id") or "")
+        for item in items
+        if isinstance(item, dict)
+        and row_id in {
+            ref for ref in (item.get("clarificationRefs") or [])
+            if isinstance(ref, str)
+        }
+        and item.get("id")
+    ]
+
+
 def _resolved_noncritical_dissent_ids(data: dict) -> set[str]:
     """Plan items whose remaining dissent the user explicitly accepted."""
     accepted: set[str] = set()
@@ -4126,22 +4197,28 @@ def _resolved_noncritical_dissent_ids(data: dict) -> set[str]:
         context = row.get("approvalContext")
         if not isinstance(context, dict):
             continue
-        resolution = context.get("resolution")
+        resolution = _clarification_resolution(row, context)
         if (
-            row.get("status") == "resolved"
-            and context.get("classification") == "noncritical-dissent"
-            and isinstance(resolution, dict)
-            and resolution.get("disposition") == "accept-risk"
-            and str(resolution.get("userText") or "").strip()
-            and _approval_context_activity_refs_exist(
-                data, str(row.get("id") or ""), context, resolution
-            )
+            row.get("status") != "resolved"
+            or context.get("classification") != "noncritical-dissent"
+            or not isinstance(resolution, dict)
+            or resolution.get("disposition") != "accept-risk"
+            or not str(resolution.get("userText") or "").strip()
         ):
+            continue
+        row_id = str(row.get("id") or "")
+        if context.get("planItemIds") or context.get("activityIds"):
+            if not _approval_context_activity_refs_exist(
+                data, row_id, context, resolution
+            ):
+                continue
             accepted.update(
                 item_id
                 for item_id in context.get("planItemIds") or []
                 if isinstance(item_id, str)
             )
+            continue
+        accepted.update(_plan_item_ids_for_clarification(row, context, data))
     return accepted
 
 
@@ -4957,14 +5034,6 @@ def _validate_resolved_approval(
             f"final-report data.json: resolved approval clarification `{row_id}` "
             "requires non-empty resolution.checkRefs."
         )
-    if (
-        context.get("classification") == "noncritical-dissent"
-        and resolution.get("disposition") != "accept-risk"
-    ):
-        failures.append(
-            f"final-report data.json: resolved noncritical-dissent `{row_id}` "
-            "requires an explicit accept-risk disposition."
-        )
 
 
 def _has_successful_targeted_reverification(item: dict) -> bool:
@@ -6173,6 +6242,7 @@ def _validate_approval_clarification_backtrace(
 
 
 _RERUN_FLAG = "--answered-clarifications"
+_USER_RESPONSE_HINT = re.compile(r"okstra-user-response", re.IGNORECASE)
 _APPROVE_HINT = re.compile(r"--approve|\bapprov", re.IGNORECASE)
 
 
@@ -6190,9 +6260,11 @@ def _next_step_texts(steps: object) -> list[str]:
     return texts
 
 
-def _has_blocks_approval_row(data: dict) -> bool:
+def _has_unresolved_approval_blocker(data: dict) -> bool:
     return any(
-        isinstance(row, dict) and row.get("blocks") == "approval"
+        isinstance(row, dict)
+        and row.get("blocks") == "approval"
+        and str(row.get("status") or "") in {"open", "answered"}
         for row in data.get("clarificationItems") or []
     )
 
@@ -6220,19 +6292,20 @@ def _validate_rerun_guidance(data: dict, failures: list[str]) -> None:
     """
     if (data.get("header") or {}).get("taskType") != "implementation-planning":
         return
-    has_blocker = _has_blocks_approval_row(data)
-    if not has_blocker:
+    if not _has_unresolved_approval_blocker(data):
         return
-    if any(_RERUN_FLAG in text for text in _next_step_texts(
-        data.get("recommendedNextSteps")
-    )):
+    texts = _next_step_texts(data.get("recommendedNextSteps"))
+    if any(_RERUN_FLAG in text for text in texts) and any(
+        _USER_RESPONSE_HINT.search(text) for text in texts
+    ):
         return
     failures.append(
-        "final-report data.json: this plan withholds approval on a "
+        "final-report data.json: this plan withholds approval on an unresolved "
         "`blocks: approval` clarification, but no `recommendedNextSteps` entry "
-        f"tells the reader how to resume — name the `{_RERUN_FLAG}` re-run in a "
-        "step's `text` or one of its `commands`. `okstra recap assemble` "
-        "prints the exact ids and flag value once the answers are recorded."
+        "tells the reader the command to run now — name `/okstra-user-response` "
+        f"and the `{_RERUN_FLAG}` re-run in a step's `text` or one of its "
+        "`commands`. `okstra recap assemble` prints the exact ids and flag "
+        "value once the answers are recorded."
     )
 
 
@@ -6247,7 +6320,7 @@ def _validate_approval_guidance(data: dict, failures: list[str]) -> None:
     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):
+    if _has_unresolved_approval_blocker(data) or _planning_gate_blocks_approval(data):
         return
     if _report_already_approved(data):
         return
@@ -7245,6 +7318,7 @@ def _validate_unresolved_tie_was_reverified(
         for item in pbv.get("planItems") or []
         if isinstance(item, dict)
         and not item.get("carriedForwardFromSeq")
+        and _stage_scope_bucket(item, pbv) == "in-scope"
         and _is_unsettled_tie(item)
     })
     if not unsettled:
@@ -7272,11 +7346,14 @@ def _validate_tie_received_extra_vote(
     pbv = ip.get("planBodyVerification")
     if not isinstance(pbv, dict):
         return
+    accepted = _resolved_noncritical_dissent_ids(data)
     missing = sorted({
         str(item.get("id") or "").strip()
         for item in pbv.get("planItems") or []
         if isinstance(item, dict)
         and not item.get("carriedForwardFromSeq")
+        and str(item.get("id") or "").strip() not in accepted
+        and _stage_scope_bucket(item, pbv) == "in-scope"
         and _is_even_blocking_split(item)
         and _distinct_verdict_workers(item) < 3
     })

package/runtime/validators/validate_analysis_report.py

@@ -54,11 +54,12 @@ _ANALYSIS_PARENT_KEYS = {
     "feature-analysis": "featureAnalysis",
     "change-impact-analysis": "changeImpactAnalysis",
 }
-_ANALYSIS_WORKER_ROLES = {
-    "Claude worker",
-    "Codex worker",
-    "Antigravity worker",
-}
+
+
+def _is_report_writer_role(role: str) -> bool:
+    return "reportwriter" in re.sub(r"[^a-z0-9]", "", role.lower())
+
+
 _FINAL_ANALYSIS_REPORT_RE = re.compile(
     r"^final-report-(?P<task_type>project-analysis|feature-analysis|"
     r"change-impact-analysis)-(?P<seq>\d{3})\.md$"
@@ -467,7 +468,7 @@ def validate_analysis_semantics(
 ) -> None:
     required_roles = _required_worker_roles(run_manifest, errors)
     analysis_worker_roles = tuple(
-        role for role in required_roles if role in _ANALYSIS_WORKER_ROLES
+        role for role in required_roles if not _is_report_writer_role(role)
     )
     verdict_roles_unambiguous = _validate_execution_status_roles(
         data, analysis_worker_roles, errors

package/runtime/validators/validate_session_conformance.py

@@ -235,8 +235,24 @@ def _worker_role(value: str) -> str | None:
 
 
 def _worker_roles(worker: dict) -> set[str]:
-    role = _worker_role(str(worker.get("role") or ""))
-    return {role, role.replace(" ", "-")} if role else set()
+    """명단 `role` 과 `workerId` 를 활동 `agent` 가 쓸 수 있는 별칭으로 펼친다.
+
+    활동은 `codex` / `codex-worker` 를 쓰고 명단은 `Codex worker` 를 쓴다.
+    역할 문자열만 보면 둘은 다른 사람이 된다.
+    """
+    roles: set[str] = set()
+    for raw in (worker.get("role"), worker.get("workerId")):
+        role = _worker_role(str(raw or ""))
+        if not role:
+            continue
+        compact = role.replace(" ", "-")
+        roles.add(role)
+        roles.add(compact)
+        if role.endswith(" worker"):
+            roles.add(role[: -len(" worker")])
+        if compact.endswith("-worker"):
+            roles.add(compact[: -len("-worker")])
+    return roles
 
 
 def _analysis_workers(team_state: Mapping[str, Any]) -> list[dict]:
@@ -1036,12 +1052,17 @@ def _check_activity_contract(
     if not _is_activity_contract_v1_planning(run_manifest):
         return
     indexed = _activity_index(evidence.activities)
+    workers = [
+        worker
+        for worker in (team_state.get("workers") or [])
+        if isinstance(worker, dict)
+    ]
     analysis_workers = _analysis_workers(team_state)
     report_data = _read_report_data(report_path)
     _check_activity_id_order(evidence.activities, errors)
     _check_projected_agent_activity(evidence.activities, report_data, errors)
     _check_activity_worker_pairs(evidence, indexed, analysis_workers, errors)
-    _check_activity_worker_agents(indexed, analysis_workers, errors)
+    _check_activity_worker_agents(indexed, workers, errors)
     _check_activity_round_counts(indexed, report_data, run_dir, suffix, errors)
     _check_activity_user_decisions(indexed, report_data, errors)