okstra 0.118.0 → 0.119.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.118.0",
+  "version": "0.119.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.118.0",
-  "builtAt": "2026-07-15T06:18:58.589Z",
+  "package": "0.119.0",
+  "builtAt": "2026-07-15T11:10:05.274Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/okstra-render-report-views.py

@@ -23,7 +23,6 @@ from __future__ import annotations
 
 import argparse
 import os
-import re
 import sys
 from pathlib import Path
 
@@ -43,7 +42,7 @@ if (SCRIPTS_DIR / "okstra_ctl" / "report_views.py").is_file():
 elif HOME_LIB.is_dir() and str(HOME_LIB) not in sys.path:
     sys.path.insert(0, str(HOME_LIB))
 
-from okstra_ctl.report_views import RunMeta, render_html_view  # noqa: E402
+from okstra_ctl.report_views import infer_run_meta, render_html_view  # noqa: E402
 
 
 _OKSTRA_HOME = Path(os.environ.get("OKSTRA_HOME", str(Path.home() / ".okstra")))
@@ -60,15 +59,6 @@ _TEMPLATES_DIRS = (
     _OKSTRA_HOME / "templates" / "reports",
 )
 
-# task-type itself can contain hyphens (``implementation-planning``,
-# ``final-verification``, ``release-handoff``), so the filename segment
-# between ``final-report-`` and ``-<seq>.md`` is matched greedily; the
-# trailing ``-(?P<seq>\d+)\.md$`` anchor pins seq to the last numeric tail.
-_PATH_RE = re.compile(
-    r"runs/(?P<task_type>[^/]+)/reports/final-report-.+-(?P<seq>\d+)\.md$"
-)
-
-
 def _load_assets() -> tuple[str, str]:
     css_text: str | None = None
     js_text: str | None = None
@@ -87,23 +77,6 @@ def _load_assets() -> tuple[str, str]:
     return css_text, js_text
 
 
-def _infer_from_path(path: Path) -> dict[str, str]:
-    posix = path.as_posix()
-    m = _PATH_RE.search(posix)
-    if m:
-        return {"task_type": m.group("task_type"), "seq": m.group("seq")}
-    return {}
-
-
-def _infer_from_body(text: str) -> dict[str, str]:
-    found: dict[str, str] = {}
-    for label, key in (("Task Key", "task_key"), ("Task Type", "task_type")):
-        m = re.search(rf"^- {label}:\s*(\S.*?)\s*$", text, re.MULTILINE)
-        if m:
-            found[key] = m.group(1)
-    return found
-
-
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         description="Render the self-contained HTML view of an okstra final-report."
@@ -119,14 +92,11 @@ def main(argv: list[str] | None = None) -> int:
     if not report_path.is_file():
         parser.error(f"final-report not found: {report_path}")
 
-    inferred = {**_infer_from_path(report_path), **_infer_from_body(report_path.read_text(encoding="utf-8"))}
-    task_key = args.task_key or inferred.get("task_key") or "unknown"
-    task_type = args.task_type or inferred.get("task_type") or "unknown"
-    seq = args.seq or inferred.get("seq") or "000"
-    source_report = args.source_report or report_path.name
-
+    meta = infer_run_meta(
+        report_path, task_key=args.task_key, task_type=args.task_type,
+        seq=args.seq, source_report=args.source_report,
+    )
     css, js = _load_assets()
-    meta = RunMeta(task_key=task_key, task_type=task_type, seq=seq, source_report=source_report)
     html_path = render_html_view(report_path, run_meta=meta, css=css, js=js)
     if html_path is None:
         print("html: skipped (no §1 clarification rows — html view carries no interactive forms for this report)")

package/runtime/prompts/launch.template.md

@@ -85,6 +85,7 @@ Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at
 - Source path: `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}`
 - If the source path above is empty, no prior clarification response was attached to this run.
 - If the source path is set, a copy is staged at `{{INSTRUCTION_SET_RELATIVE_PATH}}/clarification-response.md`. Read it before running workers; reconcile each `C-*` row in section 1 (`## 1. Clarification Items`) of the prior report against new evidence and record the outcome in the conditional `## 0. Clarification Response Carried In From Previous Run` section of this run's final report (render that heading only when carry-in is non-empty — the validator fails empty Section 0 stubs).
+- When a `## <C-id>` block carries `- Disposition: reframe`, it is not an answer but a request to re-question — the user is asking you to redefine this item. Do not treat it as answered; reconstruct the question itself in a fresh `## 1` Clarification Item, and never let a `reframe` item satisfy the approval gate.
 
 ### Incremental re-verification (implementation-planning clarification re-runs only)
 

package/runtime/python/okstra_ctl/clarification_items.py

@@ -208,6 +208,54 @@ def parse_clarification_items(report_text: str) -> Optional[list[ClarificationIt
     return _walk_section_1_table(section).items
 
 
+def parse_clarification_rows(report_text: str) -> list[dict]:
+    """§1 행마다 메타(ClarificationItem) + 원문 Statement / Expected form 셀.
+
+    ``parse_clarification_items`` 와 같은 lenient 계약: §1 부재 또는 헤더
+    미인식이면 ``[]``. §1 테이블 셀 추출의 단일 참조점 — 다른 모듈이 §1
+    레이아웃을 다시 훑지 않도록 이 함수로 통일한다.
+    """
+    section = _section_1_slice(report_text)
+    if section is None:
+        return []
+    lines = section.splitlines()
+    header_idx = -1
+    for idx, line in enumerate(lines):
+        if not line.lstrip().startswith("|"):
+            continue
+        cells = [c.lower() for c in _split_pipe_row(line)]
+        if "user input" in cells and any(c.startswith("statement") for c in cells):
+            header_idx = idx
+            break
+    if header_idx < 0:
+        return []
+    header = [c.lower() for c in _split_pipe_row(lines[header_idx])]
+    s_col = next((j for j, h in enumerate(header) if h.startswith("statement")), -1)
+    e_col = next((j for j, h in enumerate(header) if h.startswith("expected form")), -1)
+    rows: list[dict] = []
+    body = False
+    for line in lines[header_idx + 1:]:
+        if not line.lstrip().startswith("|"):
+            if body:
+                break
+            continue
+        if is_separator_row(line):
+            body = True
+            continue
+        if not body:
+            continue
+        cells = _split_pipe_row(line)
+        item = parse_meta_cell(cells[0]) if cells else None
+        if item is None:
+            continue
+        rows.append({
+            "item": item,
+            "statement": cells[s_col] if 0 <= s_col < len(cells) else "",
+            "expected_form": cells[e_col] if 0 <= e_col < len(cells) else "",
+        })
+    return rows
+
+
 UNRESOLVED_STATUSES = {"open", "answered"}
 
 

package/runtime/python/okstra_ctl/report_views.py

@@ -108,6 +108,46 @@ class RunMeta:
     source_report: str  # relative path of the .md the HTML is derived from
 
 
+# task-type itself can contain hyphens (``implementation-planning``,
+# ``final-verification``, ``release-handoff``), so the filename segment
+# between ``final-report-`` and ``-<seq>.md`` is matched greedily; the
+# trailing ``-(?P<seq>\d+)\.md$`` anchor pins seq to the last numeric tail.
+_REPORT_PATH_RE = re.compile(
+    r"runs/(?P<task_type>[^/]+)/reports/final-report-.+-(?P<seq>\d+)\.md$"
+)
+
+
+def _infer_run_meta_from_path(path: Path) -> dict:
+    m = _REPORT_PATH_RE.search(path.as_posix())
+    return {"task_type": m.group("task_type"), "seq": m.group("seq")} if m else {}
+
+
+def _infer_run_meta_from_body(text: str) -> dict:
+    found: dict[str, str] = {}
+    for label, key in (("Task Key", "task_key"), ("Task Type", "task_type")):
+        m = re.search(rf"^- {label}:\s*(\S.*?)\s*$", text, re.MULTILINE)
+        if m:
+            found[key] = m.group(1)
+    return found
+
+
+def infer_run_meta(report_path: Path, *, task_key: Optional[str] = None,
+                   task_type: Optional[str] = None, seq: Optional[str] = None,
+                   source_report: Optional[str] = None) -> RunMeta:
+    """Derive a ``RunMeta`` from a final-report path/body, honouring any
+    explicit override. Single reference point for BOTH the HTML view render
+    script and the in-session user-response writer, so sidecar match keys
+    (task_type/seq/source-report) never drift between the two paths."""
+    text = report_path.read_text(encoding="utf-8")
+    inferred = {**_infer_run_meta_from_path(report_path), **_infer_run_meta_from_body(text)}
+    return RunMeta(
+        task_key=task_key or inferred.get("task_key") or "unknown",
+        task_type=task_type or inferred.get("task_type") or "unknown",
+        seq=seq or inferred.get("seq") or "000",
+        source_report=source_report or report_path.name,
+    )
+
+
 @dataclass(frozen=True)
 class ReportViewModel:
     run_meta: RunMeta
@@ -924,6 +964,7 @@ class UserResponseEntry:
     kind: str
     value: str
     rationale: Optional[str] = None
+    disposition: str = "answer"
 
 
 @dataclass(frozen=True)
@@ -961,12 +1002,11 @@ def serialize_user_response(
     has_approval = approval is not None and approval.approved
     body_chunks: list[str] = []
     for e in entries:
-        chunk = (
-            f"\n## {e.response_id}\n"
-            f"- Kind: {e.kind}\n"
-            "- Value:\n"
-            f"  > {e.value.strip()}\n"
-        )
+        chunk = f"\n## {e.response_id}\n- Kind: {e.kind}\n"
+        if e.disposition != "answer":
+            chunk += f"- Disposition: {e.disposition}\n"
+        value_lines = e.value.strip().split("\n")
+        chunk += "- Value:\n" + "".join(f"  > {ln}\n" for ln in value_lines)
         if e.rationale:
             chunk += f"- Rationale: {e.rationale.strip()}\n"
         body_chunks.append(chunk)

package/runtime/python/okstra_ctl/user_response.py

@@ -8,10 +8,26 @@ the ``## APPROVAL`` block — the implementation wizard consumes it to offer
 """
 from __future__ import annotations
 
+import argparse
+import datetime as dt
+import json
 import re
+import sys
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Optional
 
+from okstra_ctl.report_views import (
+    serialize_user_response, UserResponseEntry, UserResponseApproval, infer_run_meta,
+)
+from okstra_ctl.report_view_artifacts import user_responses_dir_for_report
+from okstra_ctl.listing import list_runs, absolute_final_report_path
+from okstra_ctl.clarification_items import (
+    parse_clarification_rows,
+    scan_approval_gate,
+    section_1_present_but_unparsed,
+)
+
 _APPROVAL_HEADING_RE = re.compile(r"^## APPROVAL\s*$", re.MULTILINE)
 _NEXT_RESPONSE_HEADING_RE = re.compile(r"^## ", re.MULTILINE)
 
@@ -53,3 +69,177 @@ def parse_user_response_approval(
         source_report=rm.group(1) if rm else "",
         seq=sm.group(1) if sm else "",
     )
+
+
+_RESPONSE_HEADING_RE = re.compile(r"^## (?P<id>[A-Za-z][A-Za-z0-9]*-\d+)\s*$", re.MULTILINE)
+
+
+def _field(block: str, key: str) -> Optional[str]:
+    m = re.search(rf"^- {re.escape(key)}:\s*(\S.*?)\s*$", block, re.MULTILINE)
+    return m.group(1) if m else None
+
+
+def _value(block: str) -> str:
+    # Value 는 "- Value:" 다음 줄들의 "  > " 인용 블록.
+    m = re.search(r"^- Value:\s*\n((?:\s*>.*\n?)+)", block, re.MULTILINE)
+    if not m:
+        return ""
+    lines = [re.sub(r"^\s*>\s?", "", ln) for ln in m.group(1).splitlines()]
+    return "\n".join(lines).strip()
+
+
+def parse_user_response_entries(sidecar_text: str) -> list[UserResponseEntry]:
+    """Reverse of ``serialize_user_response`` for the per-response ``## C-*``
+    blocks. The ``## APPROVAL`` block is skipped (read separately by
+    ``parse_user_response_approval``)."""
+    entries: list[UserResponseEntry] = []
+    matches = list(_RESPONSE_HEADING_RE.finditer(sidecar_text))
+    for i, m in enumerate(matches):
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(sidecar_text)
+        block = sidecar_text[m.end():end]
+        rationale = _field(block, "Rationale")
+        entries.append(UserResponseEntry(
+            response_id=m.group("id"),
+            kind=_field(block, "Kind") or "",
+            value=_value(block),
+            rationale=rationale,
+            disposition=_field(block, "Disposition") or "answer",
+        ))
+    return entries
+
+
+_SEQ_FROM_REPORT_RE = re.compile(r"final-report-.+-(\w+)\.md$")
+
+
+def _seq_from_report(report: Path) -> str:
+    m = _SEQ_FROM_REPORT_RE.search(report.name)
+    return m.group(1) if m else ""
+
+
+def list_awaiting_tasks(home: Path, project_id: str, limit: int) -> list[dict]:
+    """approval-open clarification 이 있는 태스크를 최신 report mtime 순으로."""
+    seen: set[str] = set()
+    out: list[dict] = []
+    for row in list_runs(home, project=project_id, limit=0):  # startedAt desc
+        grp, tid = row.get("taskGroup", ""), row.get("taskId", "")
+        key = f"{grp}/{tid}" if grp and tid else ""
+        if not key or key in seen:
+            continue
+        seen.add(key)
+        report = absolute_final_report_path(row)
+        if report is None or not report.is_file():
+            continue
+        text = report.read_text(encoding="utf-8")
+        scan = scan_approval_gate(text)
+        base = {"taskKey": key, "taskType": row.get("taskType", ""),
+                "seq": _seq_from_report(report), "reportPath": str(report),
+                "reportMtime": report.stat().st_mtime}
+        if scan.unreadable_reason is not None:
+            # §1 heading exists but drifted → real warning; §1 simply absent → skip.
+            if section_1_present_but_unparsed(text):
+                out.append({**base, "openApprovalCount": 0, "unreadable": True})
+            continue
+        if not scan.blockers:
+            continue
+        out.append({**base, "openApprovalCount": len(scan.blockers), "unreadable": False})
+    out.sort(key=lambda t: t["reportMtime"], reverse=True)
+    return out[:limit] if limit > 0 else out
+
+
+_SECTION_REF_RE = re.compile(r"§[\d.]+|C-\d+|[\w./-]+\.\w+:\d+")
+_ALTERNATIVES_CUE = "Alternatives:"
+
+
+def _alternatives_from_expected(expected_form: str) -> list[str]:
+    idx = expected_form.find(_ALTERNATIVES_CUE)
+    if idx < 0:
+        return []
+    tail = expected_form[idx + len(_ALTERNATIVES_CUE):]
+    parts = re.split(r"[/;]", tail)
+    return [p.strip(" .,;—-") for p in parts if p.strip(" .,;—-")]
+
+
+def show_open_rows(report_path: Path) -> dict:
+    text = report_path.read_text(encoding="utf-8")
+    rows = []
+    for r in parse_clarification_rows(text):
+        it = r["item"]
+        if it.status not in ("open", "answered"):
+            continue
+        statement, expected = r["statement"], r["expected_form"]
+        refs = sorted(set(_SECTION_REF_RE.findall(statement + " " + expected)))
+        rows.append({"id": it.row_id, "kind": it.kind, "blocks": it.blocks,
+                     "status": it.status, "statement": statement,
+                     "recommended": expected,  # raw cell keeps answer + rationale
+                     "alternatives": _alternatives_from_expected(expected),
+                     "contextRefs": refs})
+    return {"reportPath": str(report_path), "rows": rows}
+
+
+def write_sidecar(report_path: Path, answers: list[dict],
+                  approval: Optional[dict], created_at: str,
+                  task_key: str = "") -> Path:
+    run_meta = infer_run_meta(report_path, task_key=task_key or None)
+    out_dir = user_responses_dir_for_report(report_path)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    sidecar = out_dir / f"user-response-{run_meta.task_type}-{run_meta.seq}.md"
+
+    merged: dict[str, UserResponseEntry] = {}
+    if sidecar.is_file():
+        for e in parse_user_response_entries(sidecar.read_text(encoding="utf-8")):
+            merged[e.response_id] = e
+    for a in answers:
+        merged[a["id"]] = UserResponseEntry(
+            response_id=a["id"], kind=a.get("kind", ""), value=a["value"],
+            rationale=a.get("rationale"), disposition=a.get("disposition", "answer"))
+
+    appr = None
+    if approval and approval.get("approved"):
+        appr = UserResponseApproval(
+            approved=True, implementation_option=approval.get("implementationOption", ""))
+    sidecar.write_text(
+        serialize_user_response(run_meta=run_meta, entries=list(merged.values()),
+                                created_at=created_at, approval=appr),
+        encoding="utf-8")
+    return sidecar
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = argparse.ArgumentParser(prog="okstra user-response")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    pl = sub.add_parser("list")
+    pl.add_argument("--home", required=True)
+    pl.add_argument("--project", required=True)
+    pl.add_argument("--limit", type=int, default=3)
+
+    ps = sub.add_parser("show")
+    ps.add_argument("--report", required=True)
+
+    pw = sub.add_parser("write")
+    pw.add_argument("--report", required=True)
+    pw.add_argument("--answers", required=True, help="JSON array of answer entries")
+    pw.add_argument("--approval", default="", help="JSON approval object")
+    pw.add_argument("--task-key", default="", help="task-key from list/show context")
+
+    ns = parser.parse_args(argv)
+    if ns.cmd == "list":
+        out = list_awaiting_tasks(Path(ns.home), ns.project, ns.limit)
+        json.dump(out, sys.stdout, ensure_ascii=False)
+        return 0
+    if ns.cmd == "show":
+        json.dump(show_open_rows(Path(ns.report)), sys.stdout, ensure_ascii=False)
+        return 0
+    if ns.cmd == "write":
+        answers = json.loads(ns.answers)
+        approval = json.loads(ns.approval) if ns.approval else None
+        created_at = dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        p = write_sidecar(Path(ns.report), answers, approval, created_at,
+                          task_key=ns.task_key)
+        json.dump({"sidecar": str(p)}, sys.stdout, ensure_ascii=False)
+        return 0
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -777,7 +777,7 @@ okstra recap note <resolved-target> --project-root <projectRoot> \
 **self-check 규칙 (validator 가 없으니 스스로 지킨다):**
 
 1. **렌더된 report 를 수기 편집하지 않는다** (`runs/*/reports/` 아래 `*.md` / `*.data.json` / `*.html`). `data.json` 에서 재생성되므로 편집은 덮어써지고 SSOT 와 어긋난다. 발견 내용은 `notes/` 에 쓴다.
-2. **`user-responses/` 파일을 작성하거나 `created-by: user` 를 달지 않는다.** 그건 사용자의 결정이며, 대신 쓰면 사용자가 내리지 않은 결정을 위조하는 것이다. 네 증거가 특정 답을 뒷받침하면 `notes/` 에 그렇게 적고 결정은 사용자에게 맡긴다.
+2. **`user-responses/` 파일을 작성하거나 `created-by: user` 를 달지 않는다.** 그건 사용자의 결정이며, 대신 쓰면 사용자가 내리지 않은 결정을 위조하는 것이다. 네 증거가 특정 답을 뒷받침하면 `notes/` 에 그렇게 적고 결정은 사용자에게 맡긴다. 단, `okstra-user-response` 스킬의 에코백 확인 흐름은 예외다 — 그 흐름에서는 사용자가 세션에서 직접 결정을 내리고 CLI 는 전사 채널일 뿐이므로, `write` 로 `created-by: user` sidecar 를 기록하는 것이 정당하다. 이 예외는 사용자가 명시적으로 "맞음" 을 확인한 뒤에만, verbatim 입력에 대해서만 성립한다.
 3. **okstra 관리 디렉토리에 쓰지 않는다** (`runs/`, `instruction-set/`, `history/`, `recap/`, `.okstra/decisions/`). `notes/` 만이 agent 소유 레인이다. `recap/recap-log.jsonl` 은 예외적으로 쓰되 손으로 편집하지 말고 `okstra recap record` CLI 로만 남긴다.
 4. **`notes/` 는 okstra 에 inert 하다** — 어떤 run 도 자동으로 읽지 않는다. 작성 후 CLI 가 출력한 `clarificationResponseArg`(예: `--clarification-response <notePath>`)를 사용자에게 그대로 알려, 다음 run 을 그 인자와 함께 실행해야만 반영된다는 것을 전한다.
 

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

@@ -0,0 +1,121 @@
+---
+name: okstra-user-response
+description: >-
+  Use this to answer an okstra task's open clarification questions in-session, without hand-editing any file. The tell is a request to respond to an okstra run's clarification items or its approval gate — "answer okstra", "I'll answer the questions", "clarification response", "user response", "approve and move on". This skill lists tasks whose latest report still has open clarification blockers, presents each open C-id (statement + recommended answer + alternatives), collects the user's own verbatim answers (or a reframe/hold), echoes the full sidecar back for an explicit "confirmed" acknowledgement, optionally records approval, and writes the `user-responses/` sidecar via `okstra user-response write`. NOT for starting a run (okstra-run), inspecting a finished task (okstra-inspect), or generating a brief (okstra-brief-gen). The skill never picks an answer for the user — it only relays recommendations and transcribes what the user decides.
+---
+
+# OKSTRA User Response
+
+Single entry point for answering the clarification questions an okstra run left behind (the open `C-*` rows under the final report's `## 1. Clarification Items`) **in-session**, and recording those answers as a `runs/<type>/user-responses/` sidecar. The next `/okstra-run` auto-attaches this sidecar via `--clarification-response`.
+
+**Core principle — the skill never picks an answer for the user.** This skill only *presents* recommendations and alternatives; every `value` is the user's own verbatim input. It never calls `write` until the user has explicitly confirmed.
+
+| Sub-command | What it does |
+|---|---|
+| `list` | List tasks that still have approval-open clarification, newest report first. |
+| `show` | Expand one report's open `C-*` rows (statement + recommended + alternatives + contextRefs). |
+| `write` | Record the collected answers (+ optional approval) as a `user-responses/` sidecar. |
+
+## Step 0: Preflight (shared)
+
+Before anything, run one Bash tool call whose leading token is the literal `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match):
+
+```bash
+okstra preflight --runtime claude-code --json
+```
+
+Branch on the stdout JSON:
+- `ok: true` → carry `projectRoot` and `projectId` as literal strings; they are the base for every step below.
+- `ok: false` → this project has no okstra setup. Tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop. If the user pointed at a specific project directory, re-run targeting it: `okstra preflight --runtime claude-code --cwd <that-dir> --json` (`--cwd` is the sanctioned way to target a project — a leading `cd` would break the permission match); only if that **also** returns `ok:false` do you stop. 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).
+
+Then resolve the okstra home once (the `list` sub-command needs it):
+
+```bash
+okstra paths --field home
+```
+
+Paste the printed path literally into `--home` below. Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
+
+## Step 1: List awaiting tasks → picker
+
+```bash
+okstra user-response list --home <resolved-home> --project <projectId> --limit 3
+```
+
+Returns a JSON array (latest report mtime first); each entry:
+`{taskKey, taskType, seq, reportPath, reportMtime, openApprovalCount, unreadable}`.
+
+- Empty array → answer `No task has open clarification items.` and stop.
+- Otherwise present a **3-option picker**: the top recommendations from the list (each shown as `taskKey (taskType, N open items)`), and the **final option is always "Enter directly"** — where the user pastes a `reportPath` or a `task-key` directly (for a task not in the top-3 window).
+- An entry with `unreadable: true` means its `## 1. Clarification Items` heading exists but drifted from the expected format. Flag it as `⚠ §1 format drift — the CLI could not parse its items` and do not proceed on it until the report is regenerated; do not fabricate rows for it.
+
+Carry the chosen entry's `reportPath` and `taskKey` forward.
+
+## Step 2: Show open rows
+
+```bash
+okstra user-response show --report <reportPath>
+```
+
+Returns `{reportPath, rows: [{id, kind, blocks, status, statement, recommended, alternatives, contextRefs}]}`. For each open `C-*` row, present to the user:
+
+- **`id`** and its **`statement`** (the original question).
+- **`recommended`** — the answer okstra proposed (+ rationale). It is only a recommendation.
+- **`alternatives[]`** — list them if present.
+- **`contextRefs[]`** — the report `§`/`C-id`/`path:line` references this question points at.
+
+## Step 3: Per-item — collect the user's decision (4 branches)
+
+For each open item, the user picks one of four dispositions. You relay and transcribe; you never choose:
+
+1. **Answer** — the user accepts the recommendation or gives their own answer. `disposition: "answer"`, `value` = the user's utterance verbatim.
+2. **Ask-to-explain** — if the user asks "what does this mean?", open the report `§`/`path:line` that this item's `contextRefs[]` points at **using Read** and explain it in plain language. Only explain — **do not pick the answer for the user**; after explaining, hand the decision back to the user.
+3. **Free-form** — the user gives a narrative answer that matches neither a recommendation nor an alternative. `value` = that narrative verbatim, with the rationale in `rationale` if needed. `disposition: "answer"`.
+4. **Hold + reframe** — if the user asks to "re-frame this question itself", record it as `disposition: "reframe"`. Put what the user wants re-asked into `value` verbatim. A reframe is not an answer, so it does not satisfy the approval gate — the next run re-frames that question.
+
+Each answer item's JSON shape: `{id, kind, value, rationale?, disposition}`. `kind` uses the same `kind` that `show` gave for that row.
+
+## Step 4: Echo the full sidecar back → explicit "confirmed" gate
+
+Once every open item is handled, **before** calling `write`, **echo back** everything collected (each `id`, `disposition`, `value`, `rationale` if present, and the approval decision from Step 5 below) to the user as-is. Then ask for explicit confirmation:
+
+> Record it as shown above? (Reply `confirmed` to write the sidecar.)
+
+- **Never call `write`** until the user says `confirmed` (or gives clear approval).
+- If the user changes any item, show the echo-back again with the changed value and re-confirm.
+- Every `value` must be the user's utterance verbatim — this gate guarantees that.
+
+## Step 5: (Optional) Record approval
+
+Record approval alongside only when the report's approval-blocking clarification items are **all filled with an answer** and the user explicitly said "approve with this option":
+
+```
+--approval '{"approved":true,"implementationOption":"<the option the user chose>"}'
+```
+
+If any approval-target item is not filled with an answer, or is a reframe/hold, do not approve — tell the user the gate is still open.
+
+## Step 6: Write the sidecar
+
+Run only after the user has confirmed the echo-back with "confirmed":
+
+```bash
+okstra user-response write --report <reportPath> --answers '<answers-json>' --approval '<approval-json>' --task-key <taskKey>
+```
+
+- `--answers` = the JSON array of `{id, kind, value, rationale?, disposition}` objects collected in Step 3.
+- `--approval` is attached only when recording approval in Step 5 (otherwise omit it).
+- `--task-key` is the value carried forward from Step 1/2.
+- Report the path from the returned JSON `{sidecar: <path>}` to the user. (`write` merges items when a sidecar already exists — the same `id` is overwritten with the new value.)
+
+## Step 7: Self-describing next-step guidance
+
+Leave the following in the final output as-is:
+
+> This answer was recorded in the `user-responses/` sidecar (`<sidecar path>`). Re-running this task's `<task-type>` with `/okstra-run` auto-attaches this answer (if you approved all approval-blocking items, the next phase is `implementation`).
+
+## Output Rules (shared)
+
+- Keep responses concise and in the language the user is using, unless they ask otherwise.
+- Give path guidance host-relative (`~/.okstra/...` or relative to the `projectRoot` preflight returned). Use repo paths only when pointing at a code source.
+- This skill never hand-edits a rendered report (`runs/*/reports/*.md` / `*.data.json`). Writing the `user-responses/` sidecar goes only through the `okstra user-response write` CLI.

package/runtime/templates/reports/report.js

@@ -144,9 +144,12 @@
       var e = entries[i];
       var chunk =
         "\n## " + e.responseId + "\n" +
-        "- Kind: " + e.kind + "\n" +
-        "- Value:\n" +
-        "  > " + trimMultiline(e.value) + "\n";
+        "- Kind: " + e.kind + "\n";
+      if (e.disposition && e.disposition !== "answer") {
+        chunk += "- Disposition: " + e.disposition + "\n";
+      }
+      var valueLines = trimMultiline(e.value).split("\n");
+      chunk += "- Value:\n" + valueLines.map(function (ln) { return "  > " + ln + "\n"; }).join("");
       if (e.rationale) {
         chunk += "- Rationale: " + trimMultiline(e.rationale) + "\n";
       }

package/runtime/templates/reports/user-response.template.md

@@ -25,6 +25,7 @@ created-at: <ISO 8601 UTC timestamp>
 ```markdown
 ## <Response ID>
 - Kind: <material | decision | data-point>
+- Disposition: <answer | reframe>   # answer(기본)면 라인 생략. reframe = 답 보류 + 재질문(행 미해결 유지)
 - Value:
   > <multi-line value, trimmed>
 - Rationale: <optional one-line rationale>

package/src/cli-registry.mjs

@@ -166,6 +166,13 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Assemble a task's run-to-run phase recap or append a recap log entry"],
   },
+  {
+    name: "user-response",
+    module: "./commands/inspect/user-response.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Answer a task's open clarification questions in-session and write the response sidecar"],
+  },
   {
     name: "rollup",
     module: "./commands/inspect/rollup.mjs",

package/src/commands/inspect/user-response.mjs

@@ -0,0 +1,26 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra user-response — 태스크의 열린 clarification 질문에 세션 내에서 답하고 sidecar 기록
+
+A thin shim over \`python3 -m okstra_ctl.user_response\`. JSON 출력.
+
+Usage:
+  okstra user-response list --home <dir> --project <id> [--limit <n>]
+  okstra user-response show --report <md>
+  okstra user-response write --report <md> --answers <json> \\
+    [--approval <json>] [--task-key <key>]
+
+Exit codes: 0 ok / 1 오류
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const { code } = await runPythonModule({
+    module: "okstra_ctl.user_response",
+    args,
+  });
+  return code ?? 1;
+}

package/src/lib/skill-catalog.mjs

@@ -16,6 +16,7 @@ export const USER_SKILL_NAMES = Object.freeze([
   "okstra-container-build",
   "okstra-graphify",
   "okstra-pr-gen",
+  "okstra-user-response",
 ]);
 
 // Names okstra used to install as skills before they were renamed or moved