okstra 0.117.0 → 0.119.0

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

@@ -18,7 +18,7 @@ Single read-side entry point for okstra runtime inspection plus the one status m
 | `cost` | Estimate file/read context cost for a task bundle. |
 | `errors` | Aggregate okstra-run error logs for a task into a timestamped markdown report; print a summary. |
 | `error-zip` | Collect cross-project okstra error logs into an anonymized zip (report + raw) and summarize clusters. |
-| `recap` | Summarize a task's run-to-run phase transitions, then answer free-form questions over its `.okstra` artifacts. Appends each summary/Q&A to `recap/recap-log.jsonl`. |
+| `recap` | Summarize a task's run-to-run phase transitions, then answer free-form questions over its `.okstra` artifacts. Appends each summary/Q&A to `recap/recap-log.jsonl`, and writes agent-authored notes to `notes/` for feeding into later runs. |
 
 ## Step 0: Preflight (shared)
 
@@ -690,7 +690,7 @@ stdout JSON 을 파싱해 보고:
 
 Trigger phrases: "okstra recap", "recap", "작업 요약", "이 task 요약", "전후 요약", "이 작업 설명해줘", "task 질문".
 
-task-id 하나에 쌓인 `.okstra` 산출물 위에서 (a) 처리 전/후 요약을 내고, (b) 그 작업에 대한 자유 질문에 답한다. 기본은 `.okstra/` 서브트리만 읽는다(artifact 모드). 사용자가 명시적으로 코드 변경까지 봐 달라고 요청할 때만 code 모드로 확장한다. 이 sub-command 는 `recap/recap-log.jsonl` 만 append 하고 `task-manifest.json` / catalog / timeline 은 절대 mutate 하지 않는다.
+task-id 하나에 쌓인 `.okstra` 산출물 위에서 (a) 처리 전/후 요약을 내고, (b) 그 작업에 대한 자유 질문에 답한다. 기본은 `.okstra/` 서브트리만 읽는다(artifact 모드). 사용자가 명시적으로 코드 변경까지 봐 달라고 요청할 때만 code 모드로 확장한다. 이 sub-command 는 `recap/recap-log.jsonl` append 와 `notes/` 노트 작성(recap.5)만 수행하고 `task-manifest.json` / catalog / timeline 은 절대 mutate 하지 않는다.
 
 ### recap.1 — Resolve target
 
@@ -748,6 +748,41 @@ okstra recap record <resolved-target> --project-root <projectRoot> \
 <이후 자유 질문을 받습니다. 코드 변경까지 보려면 "diff 까지 봐줘" 라고 요청하세요.>
 ```
 
+### recap.5 — Agent 저작 노트 (`notes/`)
+
+recap 중에 네가 **okstra task 를 위해** 만든 산출물 — 검증 증거, 설계·decision 초안, 분석 노트 — 이 앞으로의 run 에 근거로 쓰일 수 있고, 그 내용이 **렌더된 report 도 아니고 사용자 결정도 아닐 때**만 `notes/` 에 남긴다.
+
+**소유권으로 라우팅한다.** 지금 쓰려는 것이 아래 어디에 해당하는지 먼저 판별한다:
+
+| 내용 | 레인(경로) | 저작 주체 |
+|---|---|---|
+| final report 본문 | `runs/<type>/reports/*.md` (`*.data.json` 에서 렌더) | okstra 렌더러 — 절대 수기 편집 금지 |
+| clarification 에 대한 사용자 답변 | `runs/<type>/user-responses/*.md` (`created-by: user`) | 사용자만 |
+| 확정된 ADR | `.okstra/decisions/NNNN-*.md` | 승격·관리됨 |
+| **Agent 증거 / 설계 초안 / 분석** | **`.okstra/tasks/<group>/<id>/notes/`** | 너(AI) |
+
+렌더 산출물도, 사용자 결정도 아닌 **너 자신의 근거·초안**이면 `notes/` 로 간다. 노트는 손으로 찍지 말고 CLI 로 쓴다 — 경로·frontmatter·날짜를 코드가 보장하고, 다음 run 에 넘길 인자를 출력해 준다:
+
+```bash
+okstra recap note <resolved-target> --project-root <projectRoot> \
+  --kind <verification-evidence|decision-draft|analysis-note> \
+  --slug <short-topic-slug> \
+  --purpose "<한 줄 — 무엇이며 어느 run/decision 에 투입되는지>" \
+  --scope-note "<한 줄 — 무엇이 아닌지, 예: C-00x 에 대한 사용자 결정이 아님>" \
+  --body-file <노트 본문 마크다운 경로>
+```
+
+본문은 먼저 scratchpad 에 마크다운으로 쓴 뒤 `--body-file` 로 넘긴다(짧으면 `--body "<md>"` 인라인도 가능). CLI 는 `.okstra/tasks/<group>/<id>/notes/<slug>-<YYYY-MM-DD>.md` 를 생성하고 stdout JSON 으로 `notePath` 와 `clarificationResponseArg` 를 돌려준다.
+
+**self-check 규칙 (validator 가 없으니 스스로 지킨다):**
+
+1. **렌더된 report 를 수기 편집하지 않는다** (`runs/*/reports/` 아래 `*.md` / `*.data.json` / `*.html`). `data.json` 에서 재생성되므로 편집은 덮어써지고 SSOT 와 어긋난다. 발견 내용은 `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 을 그 인자와 함께 실행해야만 반영된다는 것을 전한다.
+
+**Guardrail:** `.okstra/` 는 gitignored 다 — `notes/` 는 로컬 scratch 로 취급하고 절대 `git add` 하지 않는다. 새 노트 생성은 되돌리기 쉬우니(파일 삭제), 생성물이나 사용자 소유 파일을 편집하는 것보다 항상 이쪽을 택한다.
+
 ---
 
 ## Output Rules (shared)

package/runtime/skills/okstra-pr-gen/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: okstra-pr-gen
-description: Use when the user wants to register a PR body template or generate a PR description from a branch diff using a stored (or default) template. Manages templates under ~/.okstra/template/pr and drives okstra pr {template,branches,gen}. Trigger words include "okstra pr", "PR 템플릿 등록", "PR 본문 생성", "PR 메시지 만들어", "generate PR", "pr gen", "템플릿 등록".
+description: Use when the user wants to register a PR body template or generate a PR description from a branch diff using a stored (or default) template. Manages templates under ~/.okstra/template/pr and drives okstra pr {template,branches,gen}. Trigger words include "okstra pr", "register PR template", "generate PR body", "generate PR message", "generate PR", "pr gen", and "register template".
 ---
 
 # okstra-pr-gen
@@ -31,11 +31,11 @@ If `okstra` is not on PATH, tell the user:
 
 Present a 3-option picker (`AskUserQuestion`):
 
-1. `PR 생성` — generate a PR body from a branch diff.
-2. `템플릿 등록` — save a new PR body template.
-3. `직접 입력` — always the last option (okstra picker convention).
+1. `Generate PR` — generate a PR body from a branch diff.
+2. `Register template` — save a new PR body template.
+3. `Enter manually` — always the last option (okstra picker convention).
 
-## Mode A — PR 생성
+## Mode A — Generate PR
 
 ### A1. Pick a template
 
@@ -44,7 +44,8 @@ okstra pr template list --json
 ```
 
 - If `templates` is non-empty, present a picker: 1–2 recommended templates from
-  the list, plus `기본 템플릿`(the bundled default), plus `직접 입력` last.
+  the list, plus `Default template` (the bundled default), plus `Enter manually`
+  last.
 - If empty, tell the user the bundled default template will be used.
 
 Carry the chosen template name as `<template>` (`default` for the bundled one).
@@ -55,7 +56,7 @@ Carry the chosen template name as `<template>` (`default` for the bundled one).
 okstra pr branches --json
 ```
 
-Present a 3-option base picker from `recommended` (top entries) plus `직접 입력`
+Present a 3-option base picker from `recommended` (top entries) plus `Enter manually`
 last. Carry the choice as `<base>`.
 
 ### A3. Build the generation bundle and fill the template
@@ -91,7 +92,7 @@ or not authenticated (`gh auth status` fails), leave the text in chat and tell
 the user to create the PR manually. Do not push or create the PR without the
 user's explicit confirmation.
 
-## Mode B — 템플릿 등록
+## Mode B — Register template
 
 1. Ask for a template name (`AskUserQuestion`, free text). It must match
    `^[A-Za-z0-9._-]+$`; re-ask on invalid input.

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/recap.mjs

@@ -1,15 +1,20 @@
 import { runPythonModule } from "../../lib/python-helper.mjs";
 
-const USAGE = `okstra recap — assemble a task's run-to-run phase recap, or append a recap log entry
+const USAGE = `okstra recap — assemble a task's run-to-run phase recap, append a recap log entry, or write an agent note
 
 Usage:
   okstra recap assemble <task-root|task-key> [--project-root <dir>] [--cwd <dir>]
   okstra recap record <task-root|task-key> --kind <summary|qa> --mode <artifact|code> \\
     [--question <text>] --answer <text> [--citation <path:line> ...]
+  okstra recap note <task-root|task-key> \\
+    --kind <verification-evidence|decision-draft|analysis-note> --slug <topic> \\
+    --purpose <text> --scope-note <text> (--body <markdown> | --body-file <path>)
 
 \`assemble\` is read-only and prints a JSON summary of phase transitions across runs.
 \`record\` appends one line to <task-root>/recap/recap-log.jsonl; it never mutates
 other task artifacts.
+\`note\` writes an agent-authored markdown note to <task-root>/notes/ and prints its
+path plus the \`--clarification-response\` argument for feeding it into a later run.
 `;
 
 export async function run(args) {

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