okstra 0.134.0 → 0.136.0

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

@@ -1,14 +1,16 @@
 ---
 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.
+  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, then walks the open C-ids one at a time — each rewritten as a self-contained question with background, three concrete answers (recommendation first) plus "Enter directly" — echoes the collected answers 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 — it builds the option board 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.
+**Core principle — the skill never picks an answer for the user.** It builds the option board — background, a self-contained question, three concrete answers, `Enter directly` — and the user alone picks from it; every `value` is what the user chose or typed. It never calls `write` until the user has explicitly confirmed.
+
+**Second principle — one question at a time.** Never batch two clarification items into one question, and never dump the whole open list at the user. Ask item 1, transcribe the answer, then ask item 2.
 
 | Sub-command | What it does |
 |---|---|
@@ -63,7 +65,7 @@ Returns a JSON array (latest report mtime first); each entry:
 
 Carry the chosen entry's `reportPath` and `taskKey` forward.
 
-## Step 2: Show open rows
+## Step 2: Fetch the open rows (data only — ask nothing yet)
 
 ```bash
 okstra user-response show --report <reportPath>
@@ -71,33 +73,79 @@ okstra user-response show --report <reportPath>
 
 Returns `{reportPath, rows: [{id, kind, blocks, status, statement, recommended, alternatives, contextRefs, resolvedRefs}]}`. `resolvedRefs` is `[{ref, definition}]` — the CLI has already looked up what each internal token (`RB-002`, `FU-001`, `§4.7`, …) means in the report body; `definition` is `null` only when the report text alone could not resolve it (e.g. a `path:line` pointer).
 
-**Do NOT paste the raw `statement` as the question.** A `statement` like `Rewrite RB-002 rollback (see §4.7)` is meaningless to the user on its own — that is the whole reason this skill exists. For each open `C-*` row, you MUST present:
+This call is a **data fetch, not a presentation step**. Do not print `rows` at the user, and do not paste a raw `statement` as a question — a `statement` like `Rewrite RB-002 rollback (see §4.7)` is meaningless on its own, which is the whole reason this skill exists. Announce only the count and the plan:
+
+> `<N>` open items — I'll go through them one at a time.
+
+Step 3 then turns exactly one row at a time into a question.
+
+## Step 3: Ask one item at a time (loop)
+
+Walk the open rows in report order. **One item per `AskUserQuestion` call** — never batch two items into one call, and never pre-announce the items still to come. Ask, transcribe, move on. Head each item with its position and what it is holding up:
+
+> **[2/5] C-014** — blocks: approval gate
+
+### 3a. Background first (plain text, above the picker)
+
+`AskUserQuestion` carries one sentence of question, so the background goes in the message text right before the call. Write these three blocks, **3–6 lines total** — enough that someone who never read the report can answer:
+
+1. **Situation** — what the run was doing when it stopped at this item, in the user's own domain terms.
+2. **What is undecided** — the actual fork, with every internal token expanded inline from `resolvedRefs[].definition`; the user must never need to know what `RB-002` is to answer. Say what is stuck right now in plain words: `blocks: approval` → the approval gate stays shut and `implementation` cannot start; `blocks: next-phase` → the next phase cannot begin.
+3. **What changes with your answer** — what each direction actually causes downstream.
+
+Where the background comes from — in this order:
+
+- `resolvedRefs[].definition`, which is already resolved and needs no file read;
+- when a `definition` is `null`, or the three blocks would otherwise be empty, **Read** the report `§`/`path:line` that this item's `contextRefs[]` points at and take it from there;
+- **never invent it.** If the report genuinely does not say why, write `The report states nothing beyond the statement itself.` and go straight to the question. Fabricated background corrupts the answer it collects.
+
+Close the background with the raw source on one line, so the mapping back to the report stays visible:
+
+> Source: `C-014` — "<raw statement>"
+
+### 3b. The picker — three answers plus `Enter directly`
+
+One `AskUserQuestion` (single-select), with exactly four options in this order:
+
+1. **The recommendation** — the answer from `recommended` restated in plain language, label suffixed `(Recommended)`; its description carries the rationale (the part of the `recommended` cell after `—`).
+2. **Alternative** — `alternatives[0]`.
+3. **Alternative** — `alternatives[1]`.
+4. **`Enter directly`** — always last, always present.
+
+Slots 2–3 fill from `alternatives[]` first. When `alternatives[]` is short, fill each remaining slot with the first of these that applies:
+
+- **a concrete candidate the report itself names** — another option row, an approach §2 rejected, a value already in use elsewhere. Its description must open with `Not an okstra proposal — from <where>` and cite that source.
+- **`Reframe this question`** — the item is held rather than answered, and the next run re-asks it.
+
+That last entry is what guarantees the picker always reaches three answers plus `Enter directly`. Never pad a slot with an option no source supports, and never mark anything but `recommended` as recommended.
+
+Keep each `label` to the answer itself (1–5 words); the description carries the consequence.
+
+### 3c. Transcribe the decision, then move on
 
-- **A rewritten, self-contained question** (lead with this): rewrite `statement` in plain language with **every internal token expanded inline** from its `resolvedRefs` `definition` — the user must never have to know what `RB-002` is to answer. If a token's `definition` is `null`, resolve it yourself **using Read** on the report `§`/`path:line` before asking; only if it is genuinely unresolvable do you say so plainly.
-- **`recommended`** — the answer okstra proposed (+ rationale), also stated in plain language. It is only a recommendation.
-- **`alternatives[]`** — list them if present, each in plain language.
-- **Raw source** (secondary, for traceability): the raw `id` + `statement` so the mapping back to the report stays visible.
+Record one entry — `{id, kind, value, rationale?, disposition}`, `kind` copied from the row `show` returned:
 
-## Step 3: Per-item — collect the user's decision (4 branches)
+| The user picks | `value` | `disposition` |
+|---|---|---|
+| Option 1–3 | that option's full answer text, not its short label | `answer` |
+| `Enter directly` → their own answer | the user's utterance verbatim (rationale into `rationale`) | `answer` |
+| `Reframe this question`, or free text asking for it to be re-asked | what the user wants re-asked, verbatim (empty → the raw statement) | `reframe` |
 
-For each open item, the user picks one of four dispositions. You relay and transcribe; you never choose:
+A reframe is not an answer, so it does not satisfy the approval gate.
 
-1. **Answer** — the user accepts the recommendation or gives their own answer. `disposition: "answer"`, `value` = the user's utterance verbatim.
-2. **Ask-to-explain (fallback)** — Step 2 already expanded every internal token, so the question should already be self-contained. If the user still asks "what does this mean?" or a `resolvedRefs` `definition` was `null`, 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.
+If the user replies with a question instead of an answer ("what does this mean?"), record nothing: **Read** the `§`/`path:line` from `contextRefs[]`, explain it in plain language, and re-ask the same item with the same four options. Explain only — **do not resolve it for them**; the decision goes back to the user.
 
-Each answer item's JSON shape: `{id, kind, value, rationale?, disposition}`. `kind` uses the same `kind` that `show` gave for that row.
+Echo one line per finished item (`[2/5] C-014 → answer: 60s`), then ask the next one. Do not summarize the whole set until Step 4.
 
 ## 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:
+Once the loop has covered every open item, **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.
+- Every `value` must be what the user picked or typed, never a wording you settled on for them — this gate guarantees that.
 
 ## Step 5: (Optional) Record approval
 

package/runtime/validators/forbidden_actions.py

@@ -166,7 +166,7 @@ def scan_forbidden_actions(
         resolve_team_needles_with_source,
     )
 
-    since, until = resolve_run_window(team_state_path, team_state)
+    since, until = resolve_run_window(team_state_path, team_state, relax_start=False)
     lead_sid = (team_state.get("lead") or {}).get("sessionId") or ""
     team_needles, _needle_source = resolve_team_needles_with_source(
         team_state, project_root, since, until, projects_root=claude_projects_dir

package/runtime/validators/validate-run.py

@@ -43,6 +43,7 @@ from okstra_ctl.conformance import (  # noqa: E402
     qa_result_from_dict,
     validate_conformance_manifest,
 )
+from okstra_ctl.paths import RunRef  # noqa: E402
 from okstra_ctl.md_table import (  # noqa: E402
     is_separator_row as _is_markdown_separator,
     split_pipe_row as _split_pipe_row,
@@ -1143,17 +1144,15 @@ def _scope_manifest_entries(manifest: dict, stage_name: str | None) -> dict:
 
 
 def _task_root_from_run_dir(run_dir: Path) -> Path:
-    """run_dir 에서 `runs` 디렉터리를 앵커로 task_root 를 복원한다.
+    """run_dir 에서 task_root 를 복원한다.
 
-    일반 task-type: run_dir = task_root/runs/<task-type> → task_root.
-    implementation(stage 격리): run_dir = task_root/runs/implementation/stage-<N>
-    → 같은 task_root. `runs` 를 위로 탐색하므로 stage-<N> 레벨이 추가돼도
-    안전하다. `runs` 가 조상에 없으면 기존 동작(두 단계 위)로 폴백한다.
+    레이아웃 해석은 `RunRef.from_run_dir` 이 소유한다. run 디렉터리가 아닌
+    입력에는 기존 동작(두 단계 위)으로 폴백해 검증기가 죽지 않게 한다.
     """
-    for parent in run_dir.parents:
-        if parent.name == "runs":
-            return parent.parent
-    return run_dir.parent.parent
+    try:
+        return RunRef.from_run_dir(run_dir).task_root
+    except ValueError:
+        return run_dir.parent.parent
 
 
 def _read_run_inputs_payload(
@@ -3129,19 +3128,15 @@ _PASSING_VERDICT_TOKENS = frozenset({"accepted", "conditional-accept"})
 def _consumers_rows(report_path: Path) -> list[dict] | None:
     """`runs/implementation-planning/consumers.jsonl` rows for this task.
 
-    The final-verification report sits at `runs/final-verification/[stage-N/]
-    reports/...`, so walk up to the `runs/` directory rather than guessing a
-    fixed depth. ``None`` when the file is absent, so the caller does not turn
-    a missing artifact into a false accusation.
+    ``None`` when the report path is unreadable as a run reference or the file
+    is absent, so the caller does not turn a missing artifact into a false
+    accusation.
     """
-    runs_dir = None
-    for parent in report_path.parents:
-        if parent.name == "runs":
-            runs_dir = parent
-            break
-    if runs_dir is None:
+    try:
+        ref = RunRef.from_report_path(report_path)
+    except ValueError:
         return None
-    path = runs_dir / "implementation-planning" / "consumers.jsonl"
+    path = ref.sibling("implementation-planning").run_dir / "consumers.jsonl"
     if not path.is_file():
         return None
     rows = []
@@ -3497,8 +3492,11 @@ def _validate_stage_carry_sidecar_exists(
     stage = evidence.get("stageNumber")
     if not isinstance(stage, int):
         return
-    # `report_path` is `runs/implementation/reports/final-report-...md`.
-    carry_path = report_path.parent.parent / "carry" / f"stage-{stage}.json"
+    # Carry sidecars are stage-SHARED: the next stage's carry-in and
+    # `consumers.backfill_done_from_carry` glob them without knowing the
+    # producing run's layout. `RunRef.carry()` owns that flat-vs-staged rule;
+    # resolving it under the stage run dir forced the lead to write it twice.
+    carry_path = RunRef.from_report_path(report_path).carry(stage)
     if not carry_path.exists():
         failures.append(
             f"implementation run declares stage-{stage} sidecar evidence but "

package/runtime/validators/validate_session_conformance.py

@@ -194,7 +194,7 @@ def _collect_lead_evidence(
     )
     from okstra_token_usage.paths import claude_project_dir
 
-    since, until = resolve_run_window(team_state_path, team_state)
+    since, until = resolve_run_window(team_state_path, team_state, relax_start=False)
     lead_sid = (team_state.get("lead") or {}).get("sessionId") or ""
     team_needles, _needle_source = resolve_team_needles_with_source(
         team_state, project_root, since, until, projects_root=projects_root