okstra 0.189.3 → 0.190.0

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -1,6 +1,8 @@
 """Compact initial final-verification prompt contract."""
 from __future__ import annotations
 
+from .agent.invocation import EXECUTION_DELIVERY_PREFIXES
+
 import json
 import re
 from dataclasses import dataclass
@@ -73,6 +75,7 @@ _REQUIRED_TARGET_PREFIXES = (
     "**Verification target digest:**",
 )
 _WORKER_SPECIFIC_PREFIXES = (
+    *EXECUTION_DELIVERY_PREFIXES,
     "**Prompt History Path:**",
     "**Result Path:**",
     "**Audit sidecar path:**",
@@ -221,9 +224,8 @@ def validate_analysis_prompt_set(prompts: Mapping[str, str]) -> list[str]:
     return [f"normalized initial analysis prompts differ across workers: {workers}"]
 
 
-# reverify 응답 계약 블록. `prompts/lead/convergence.md`
-# §"Required reverify output contract (BLOCKING)" 가 정본이고, 리드는 그 블록을
-# 변종별 응답 형식 뒤에 그대로 덧붙인다.
+# 재검증 출력 계약의 정본은 templates/reverify-output-contract.md 이다.
+# 기존 수기 입력의 공백 차이는 허용하면서 세 조항의 의미를 검사한다.
 #
 # 바이트 단위로 비교하지 않는다 — 손으로 복사하는 블록이라 공백·줄바꿈이 흔들리고,
 # 그 흔들림으로 디스패치를 막으면 규칙이 아니라 서식을 강제하게 된다. 세 항목이
@@ -247,6 +249,8 @@ def _validate_output_contract_block(text: str) -> list[str]:
             f"`{_OUTPUT_CONTRACT_HEADING}` block is required "
             "(convergence.md §\"Required reverify output contract\")"
         ]
+    if text.count(_OUTPUT_CONTRACT_HEADING) != 1:
+        return ["exactly one Output Contract block is required"]
     tail = text.split(_OUTPUT_CONTRACT_HEADING, 1)[1]
     missing = [
         label
@@ -313,6 +317,42 @@ def validate_reverify_prompt(
     return errors
 
 
+def complete_reverify_instruction(
+    body: str, *, task_type: str, forbidden_actions: str,
+    model: str, output_contract: str,
+) -> str:
+    """수기 입력의 일치하는 경계는 유지하고 빠진 실행 계약만 생성한다."""
+    prefix = []
+    models = _header_values(body, MODEL_HEADER)
+    if not models:
+        prefix.append(f"{MODEL_HEADER} {model}")
+    elif _validate_model_header(body, model):
+        raise ValueError(f"Model conflicts: expected {model!r}")
+    tasks = _header_values(body, TASK_TYPE_HEADER)
+    if not tasks:
+        prefix.append(f"{TASK_TYPE_HEADER} {task_type}")
+    elif tasks != [task_type]:
+        raise ValueError(f"Task Type conflicts: expected {task_type!r}, got {tasks!r}")
+    actions = _section_values(body, FORBIDDEN_ACTIONS_HEADER)
+    if any(_header_values(body, FORBIDDEN_ACTIONS_HEADER)):
+        raise ValueError(f"Forbidden actions conflicts: put the exact block after {FORBIDDEN_ACTIONS_HEADER}")
+    if not actions:
+        prefix.extend([FORBIDDEN_ACTIONS_HEADER, forbidden_actions.strip()])
+    elif actions != [forbidden_actions.strip()]:
+        raise ValueError(f"Forbidden actions conflicts: expected {forbidden_actions.strip()!r}, got {actions!r}")
+    if prefix:
+        # 금지 목록 뒤의 일반 문장이 목록 값에 합쳐지지 않도록 경계를 만든다.
+        if not body.lstrip().startswith(("## ", "**")):
+            body = "## Instructions\n\n" + body
+        body = "\n".join(prefix) + "\n\n" + body
+    if _OUTPUT_CONTRACT_HEADING not in body:
+        body = body.rstrip() + "\n\n" + output_contract.strip() + "\n"
+    errors = _validate_output_contract_block(body)
+    if errors:
+        raise ValueError("; ".join(errors))
+    return body
+
+
 def _task_instructions_offset(text: str) -> int:
     """Where the lead's own instruction body starts.
 

package/runtime/python/okstra_ctl/worker_prompt_headers.py

@@ -150,9 +150,23 @@ def worker_prompt_headers(
         )
     if _string_value(manifest.get("taskType")) == "final-verification":
         headers.extend(_final_verification_target_headers(active_context))
+    else:
+        headers.extend(source_worktree_headers(active_context))
     return headers
 
 
+def source_worktree_headers(active_context: Mapping[str, Any]) -> list[str]:
+    worktree = active_context.get("executorWorktree")
+    path = _string_value(worktree.get("path")) if isinstance(worktree, Mapping) else ""
+    if not path:
+        return []
+    return [
+        f"**Worktree:** {path}",
+        "Read project source from Worktree; resolve .okstra artifacts "
+        "and Result Path against Project Root.",
+    ]
+
+
 def _worker_provider(manifest: Mapping[str, Any], worker_id: str) -> str:
     """이 워커를 실행할 공급자.
 

package/runtime/python/okstra_ctl/workflow.py

@@ -125,12 +125,12 @@ PHASE_RULES: dict[str, dict[str, str]] = {
         "allowed": (
             "  - acceptance verdict with requirement coverage assessment\n"
             "  - residual risk and regression notes\n"
-            "  - routing recommendation as the `routingRecommendation` object `{target, rationale}`: `target` is one of `release-handoff`, `release-handoff(stage-group)`, `error-analysis`, `implementation-option-selection`, `implementation-planning`, `implementation`, `done`, and `rationale` ties that choice to the verdict and the blocker list. Both `release-handoff` forms require the `accepted` verdict; plain `release-handoff` additionally requires `whole-task` verification scope. Prose alone does not route the task — Phase 7 projects `workflow.nextRecommendedPhase` from `target`"
+            "  - routing recommendation as the `routingRecommendation` object `{target, rationale}`: `target` is one of `release-handoff`, `release-handoff(stage-group)`, `error-analysis`, `implementation-option-selection`, `implementation-planning`, `implementation`, `done`, and `rationale` ties that choice to the verdict and the blocker list. Both `release-handoff` forms require a release-ready verdict — `accepted`, or `conditional-accept` with every condition declaring `blocksReleaseHandoff: false` (`okstra_ctl.release_gate.release_handoff_allowed`); plain `release-handoff` additionally requires `whole-task` verification scope. Prose alone does not route the task — Phase 7 projects `workflow.nextRecommendedPhase` from `target`"
         ),
     },
     "release-handoff": {
         "allowed": (
-            "  - entering this phase only when the cited final-verification report's `Verdict Token` is exactly `accepted`\n"
+            "  - entering this phase only when the cited final-verification report's verdict is release-ready — `Verdict Token` exactly `accepted`, or exactly `conditional-accept` with every Conditional Acceptance Condition row declaring `blocksReleaseHandoff: false` (`okstra_ctl.release_gate.release_handoff_allowed`)\n"
             "  - asking the user (via `AskUserQuestion` / interactive prompt) which delivery action to take: `local checkout`, `push + PR`, or `skip` (end the run)\n"
             "  - asking the user to pick a PR base branch from `staging` | `preprod` | `prod` | `main` | `dev` | a user-supplied branch name\n"
             "  - drafting PR title and PR body **inline as the Okstra lead** (no drafter worker and no delegated dispatch); the lead reviews its own draft with the user before any mutating git / gh command runs\n"

package/runtime/python/okstra_ctl/worktree/__init__.py

@@ -58,6 +58,7 @@ from .git_ops import (
     is_git_work_tree,
     main_worktree_path,
     merge_branch,
+    move_worktree,
     remove_worktree_force,
 )
 from .naming import compute_branch_name, compute_worktree_path
@@ -87,6 +88,7 @@ __all__ = [
     "preview_worktree_decision",
     "provision_stage_worktree",
     "provision_task_worktree",
+    "move_worktree",
     "remove_worktree_force",
     "resolve_stage_worktree_decision",
 ]

package/runtime/python/okstra_ctl/worktree/cleanliness.py

@@ -40,10 +40,13 @@ def okstra_clean_gate_excludes(project_root: Optional[Path] = None) -> tuple[str
 def nested_worktree_excludes(worktree_path) -> tuple[str, ...]:
     """Relative paths of git worktrees nested under `worktree_path`.
 
-    implementation stage worktrees live inside the task worktree
-    (`<task-id>/stage-<N>/`), so the parent's `git status --short` reports
-    each as an untracked `?? stage-N/`. They are git-registered worktrees,
-    not user source changes, so clean gates must ignore them. Derived from
+    implementation stage worktrees used to live inside the task worktree
+    (`<task-id>/stage-<N>/`), so the parent's `git status --short` reported
+    each as an untracked `?? stage-N/`. New stage worktrees are siblings
+    (`<task-id>--stage-<N>`, `worktree.naming`) and whole-task
+    final-verification prepare moves the remaining nested ones out, so this
+    normally returns an empty tuple now — it stays because a task that has not
+    been through that prepare still has the nested layout. Derived from
     `git worktree list` rather than a hardcoded pattern so it tracks exactly
     what git registered.
     """

package/runtime/python/okstra_ctl/worktree/git_ops.py

@@ -157,6 +157,13 @@ def merge_branch(cwd, branch: str, *, no_ff: bool) -> list[str] | None:
     return conflicts
 
 
+def move_worktree(cwd, worktree_path, new_path) -> subprocess.CompletedProcess:
+    """등록된 worktree 를 다른 경로로 옮긴다(`git worktree move`). 내용·브랜치·
+    등록은 그대로고 경로만 바뀐다. 중첩 stage worktree 를 task worktree 밖으로
+    꺼내는 단일 지점이다."""
+    return _git(Path(cwd), "worktree", "move", str(worktree_path), str(new_path))
+
+
 def remove_worktree_force(cwd, worktree_path) -> subprocess.CompletedProcess:
     """워크트리를 강제 제거한다. provision_*_worktree 가 워크트리에 .okstra·
     synced 디렉터리/파일 symlink(untracked) 를 깔기 때문에 plain remove 는 그

package/runtime/python/okstra_ctl/worktree/naming.py

@@ -50,10 +50,19 @@ def compute_worktree_path(
     stage_number: Optional[int] = None,
     group_id: Optional[str] = None,
 ) -> Path:
-    """Pure path computation. One worktree dir per task-key, or per
-    `<task-key>/stage-<N>` when stage_number is given (implementation
-    stage isolation). Uses `OKSTRA_HOME` when set (test hook), else
-    `~/.okstra`."""
+    """Pure path computation. One worktree dir per task-key, or the sibling
+    `<task-key>--stage-<N>` when stage_number is given (implementation stage
+    isolation). Uses `OKSTRA_HOME` when set (test hook), else `~/.okstra`.
+
+    stage worktree 는 task worktree 의 *형제* 다. 종전에는 `<task>/stage-<N>/`
+    로 안에 두었는데, 그 트리는 task worktree 의 `git status` 에 `?? stage-N/`
+    로 잡히고 프로젝트의 prettier·tsc 가 소스로 읽었다 — 실측(2026-09-06,
+    fontsninja-v3-site final-verification 001): `pnpm prettier:check` 가
+    `stage-1/.next/**` 1,107건으로, `pnpm build` 가 `stage-1/src/**` 의 중복
+    전역 선언으로 실패해 두 검증자가 이를 acceptance blocker 로 합의했다.
+    whole-task final-verification 은 판정 뒤까지 stage worktree 를 남기므로
+    (`stage_targets`, `teardown=False`) 검증 대상 트리에서 그 디렉터리가 사라질
+    길이 없었다. 형제 배치는 git·도구·변이 감사 모두에게 같은 답이 된다."""
     if stage_number is not None and group_id is not None:
         raise ValueError("stage_number and group_id are mutually exclusive")
     base = okstra_home()
@@ -64,9 +73,9 @@ def compute_worktree_path(
         / _safe_segment(task_id_segment)
     )
     if stage_number is not None:
-        path = path / f"stage-{stage_number}"
+        path = path.with_name(f"{path.name}--stage-{stage_number}")
     if group_id is not None:
-        path = path / f"group-{group_id}"
+        path = path.with_name(f"{path.name}--group-{_safe_segment(group_id)}")
     return path
 
 

package/runtime/python/okstra_ctl/worktree/provision.py

@@ -273,7 +273,8 @@ def provision_stage_worktree(
 
     Unlike `provision_task_worktree` (one worktree per task-key shared
     across phases), this provisions a per-stage worktree branched from
-    `base_commit` at `<task-key>/stage-<N>/` on branch `<prefix>-<task>-s<N>`.
+    `base_commit` at `<task-key>--stage-<N>` (a sibling of the task worktree) on
+    branch `<prefix>-<task>-s<N>`.
     The stage-key (`<task-key>#stage-<N>`) is reserved atomically through
     `worktree_registry`; re-entry of the same stage-key returns the
     existing entry. Branch / on-disk conflicts roll back the worktree

package/runtime/python/okstra_ctl/worktree_registry.py

@@ -177,6 +177,33 @@ def reserve(
         return WorktreeEntry(task_key=key, **row)
 
 
+def relocate_worktree(
+    project_id: str, task_group: str, task_id: str, *,
+    stage_number: Optional[int], worktree_path: str,
+) -> dict:
+    """Record that a registered worktree now lives at `worktree_path`.
+
+    `git worktree move` 가 디스크와 git 등록을 옮긴 뒤 호출한다. 이전 경로는
+    `relocated_from` 에 누적해 남긴다 — 옮긴 사실이 사라지면 옛 경로를 적은
+    산출물(런 매니페스트, 프롬프트)을 읽는 쪽이 그 디렉터리를 찾지 못하는
+    이유를 알 수 없다. 행이 없으면 RuntimeError.
+    """
+    key = task_key(project_id, task_group, task_id, stage_number)
+    with _registry_lock():
+        data = _load()
+        row = data["tasks"].get(key)
+        if not row:
+            raise RuntimeError(f"worktree registry has no row for {key}")
+        previous = row.get("worktree_path", "")
+        if previous != worktree_path:
+            history = list(row.get("relocated_from") or [])
+            history.append(previous)
+            row["relocated_from"] = history
+            row["worktree_path"] = worktree_path
+            _save(data)
+        return dict(row)
+
+
 def touch_phase(project_id: str, task_group: str, task_id: str, phase: str) -> None:
     """Record the most recent phase observed on this worktree.
     Best-effort: silently no-ops if the task-key is not registered.

package/runtime/python/okstra_ctl/wrapper_status.py

@@ -17,6 +17,9 @@ class WrapperStatus:
     timeout: bool
     log_path: Path | None
     raw: Mapping[str, Any]
+    # wrapper 가 init 에 기록한 자기 pid (`okstra-wrapper-status.py init`). 상태
+    # 파일을 못 쓰고 죽은 프로세스를 await 가 알아보는 유일한 단서다.
+    pid: int | None = None
 
     @property
     def is_terminal(self) -> bool:
@@ -82,6 +85,7 @@ def read_wrapper_status(path: Path) -> WrapperStatus | None:
         timeout=raw.get("timeout") is True,
         log_path=_optional_path(raw.get("log_path")),
         raw=raw,
+        pid=_optional_int(raw.get("pid")),
     )
 
 

package/runtime/schemas/final-report-v2.0.schema.json

@@ -3940,6 +3940,10 @@
       ],
       "additionalProperties": false,
       "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^R-[0-9]{3,}$"
+        },
         "originalRequirementId": {
           "type": "string",
           "pattern": "^(EB|PB|EO)-[0-9]{3}$"

package/runtime/schemas/final-report-v3.0.schema.json

@@ -4050,6 +4050,10 @@
       ],
       "additionalProperties": false,
       "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^R-[0-9]{3,}$"
+        },
         "originalRequirementId": {
           "type": "string",
           "pattern": "^(EB|PB|EO)-[0-9]{3}$"

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

@@ -222,6 +222,11 @@ Order of operations:
    questions into one. When you relay this preflight, tell the user in one
    line *why* task group comes first (it scopes where this ticket's brief —
    and any sub-ticket briefs — are written).
+
+   **Enforced:** `validators/validate-brief.py` requires the brief's
+   directory segment to equal the slugified frontmatter `task-group`, so a
+   brief written before the group is known — or under an invented placeholder
+   group — fails validation rather than landing in the wrong tree.
 1. `AskUserQuestion` (free text):
    `"Ticket key or URL (e.g. LIN-1234, PROJ-42, https://linear.app/..., https://your.atlassian.net/browse/...)"` →
    `ticket_ref`. Issue this only **after** Step 2a's task-group answer is in
@@ -451,6 +456,8 @@ to Source Material body, not to the filename):
 Validate the full `<ticket-id>-<file-title>` slug: must have at least one
 alphanumeric character after slugification. Apply Step 2c on collision.
 
+**Enforced:** `validators/validate-brief.py` checks the brief's filename and its task-group directory segment against the slugified frontmatter `task-group`, and rejects a Source Material section whose entry does not match the source it names.
+
 ### 2c. Collision handling
 
 If a brief file already exists, `AskUserQuestion` with (`Skip` /
@@ -546,6 +553,8 @@ empty or trivially thin **after** reading Source Material verbatim, ask **at
 most one** `AskUserQuestion` to fill it. Never ask about sections already
 covered by the source material.
 
+**Enforced:** `validators/validate-brief.py` fails a brief whose required section is missing, is left as a template placeholder (`is_placeholder`), or carries only the template's own example lines (`is_template_example`) — so a section skipped here does not pass as filled.
+
 ### Sharpening pass (bounded grill)
 
 The following rules absorb the useful parts of `grill-me` /
@@ -656,6 +665,8 @@ labels. Unlabelled augmentation is rejected as half-formed translation.
 **Inline form** — `> augmented: intent-inference — <one line>`.
 **Section form** — `- intent-inference: <one line>` under `Augmentation`.
 
+**Enforced:** `validators/validate-brief.py` reads both forms (`inline_augmented_blockquotes`, `augmentation_entries`) and fails a brief whose entry carries a label outside this table (`parse_augmentation_label`).
+
 ### Auto-mirroring rule
 
 Every `intent-inference` entry must have a paired entry in `Open Questions`
@@ -1014,13 +1025,21 @@ per-page ratio instead of origin load). If the file is absent, ask once via
 
 Never fill the skeleton yourself from the tickets: a ticket summary decides
 nothing, and the sections ask for what the tickets do not say. If the file
-exists, leave it untouched and mention its path in the hand-off block.
+exists, leave it untouched and mention its path in the hand-off block. The
+file's trailing `## Task Memory` region (between `<!-- okstra:task-memory:begin -->`
+and `end`) is okstra's: `report-finalize` rewrites it after every run with the
+group's start order and each task's latest conclusion, and a group whose
+runs finished before anyone created the file already has one holding that
+region alone — `init` then inserts the human sections above it.
 
 Then stop. Do not invoke `okstra-run` directly — the user chooses when to
 proceed, and they may want to edit the brief externally first. In the
 multi-brief case the user also decides the order in which tasks are
-started. When a skeleton was created in 7a, add one line to the hand-off
-block:
+started; the brief ordinal in each brief id (`<TICKET>-<n>-<slug>`) is what
+okstra reads as the group's start order (`Related Task Graph` edges are
+quoted beside it as `waits for`, never reordering), so number the briefs in
+the order the user wants them started. When a
+skeleton was created in 7a, add one line to the hand-off block:
 
 ```
 group context skeleton: <abs>/<task-group>/group-context.md   (fill before /okstra-run)

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

@@ -48,10 +48,12 @@ If the host has a native picker, use it. Otherwise print a numbered list.
 1. Run `okstra chat rooms`.
 2. If the output is `no rooms`, say so and offer create.
 3. Otherwise pick a room from that list (picker, or numbered list if the picker limit is exceeded).
-4. Ask for the display name as free input.
-5. Run `okstra chat join --room <room> --name <display>`.
+4. Run `okstra chat members --room <room>`.
+5. Ask for the display name as free input.
+6. If that name is not in the members output, run `okstra chat join --room <room> --name <display>`.
+7. If that name is already in the members output, ask one question: is this session already in the room under that name (for example, it joined before the conversation was summarized)? If yes, do not run join; continue with `--as <display>`. If no, ask for a different display name and go back to 6.
 
-`--name` is required. An empty name, `all`, or a name already in the room fails.
+`--name` is required. An empty name, `all`, or a name already in the room fails. `display name already taken` after a context loss means step 7, not a new name.
 
 ## Step 2: Unread
 
@@ -59,7 +61,7 @@ If the host has a native picker, use it. Otherwise print a numbered list.
 okstra chat unread --room <room> --as <display>
 ```
 
-Show the rows. Each row is `id @from YYYY-MM-DD HH:MM body`. Sender is always `@name`. The id is the first token (before the first space). A reply inserts `↑<parentId>` after the time. Recipient is not on the line.
+Show the rows. Each row is `id @from YYYY-MM-DD HH:MM body`. Sender is always `@name`. The id is the first token (before the first space). A reply inserts `↑<parentId>` after the time. Recipient is not on the line. A body with several lines continues on the following rows; those rows start with two spaces and carry no id.
 
 If the output is `no unread`, do not ack.
 
@@ -69,7 +71,7 @@ If there are unread rows, always run:
 okstra chat ack --room <room> --as <display> --through <id>
 ```
 
-Use the last unread row's id. CLI unread does not move the cursor; this ack does.
+Use the id of the last row that starts with an id. CLI unread does not move the cursor; this ack does. Ack never moves the cursor backwards.
 
 ## Step 3: Next action
 
@@ -81,7 +83,7 @@ There is no ack menu item. Choosing unread again shows the rows then acks, same
 
 1. Run `okstra chat members --room <room>`.
 2. Pick the recipient from `all` plus those names except the current display name (`--as`). Filter after `okstra chat members`. Do not pass `--as` to `members`. Recipient is required.
-3. Ask for the body as free input.
+3. Ask for the body as free input. The body may span several lines; pass it as one `--body` argument.
 4. Run `okstra chat send --room <room> --as <display> --to <all|name> --body <text>`.
 
 ### Reply

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

@@ -1,7 +1,7 @@
 ---
 name: okstra-inspect
 description: >-
-  Use this for everything that happens AFTER a single okstra task has already run — inspecting it or light bookkeeping on it, never launching new work. The tell is usually a named task id (PROD-1623, dev-9184), often dropped without the word "okstra." Reach for it when the user wants one task's: status, current/next phase, blockers, or approval gate; its final report — where it is or whether it passed (verdict / pass); its elapsed time or context/read cost; its run history, re-run, or resume; to mark it done / in-progress / blocked / todo; or a failed run's error logs gathered into a report (error report). Also turns cross-project okstra errors into an anonymized zip (error feedback), and audits run health across tasks (run audit). NOT for starting a run (okstra-run), rollups/schedules (okstra-rollup / okstra-schedule-gen), a brief (okstra-brief-gen), setup (okstra-setup), or cross-project management (okstra-manager).
+  Use this for everything that happens AFTER an okstra task has already run — inspecting it or light bookkeeping, never launching new work. The tell is usually a named task id (PROD-1623, dev-9184) without the word "okstra." Reach for it when the user wants one task's: status, current/next phase, blockers, or approval gate; its final report — where it is or whether it passed; its elapsed time or context/read cost; its run history, re-run, or resume; to mark it done / in-progress / blocked / todo; or a failed run's error logs gathered into a report. The recap facet also takes a task-group: which briefs are done / in progress / not started, what is next, each task's latest conclusion. Also builds an anonymized cross-project error zip and audits run health. NOT for starting a run (okstra-run), a group's run/time/error totals (okstra-rollup), schedules (okstra-schedule-gen), a brief (okstra-brief-gen), setup (okstra-setup), or cross-project management (okstra-manager).
 ---
 
 # OKSTRA Inspect
@@ -19,7 +19,7 @@ Single read-side entry point for okstra runtime inspection plus the one status m
 | `errors` | `facets/errors.md` | Aggregate okstra-run error logs for a task into a timestamped markdown report; print a summary. |
 | `error-zip` | `facets/error-zip.md` | Collect cross-project okstra error logs into an anonymized zip (report + raw) and summarize clusters. |
 | `run-audit` | `facets/run-audit.md` | Check every run's artifacts against progress invariants; report what went wrong without an error ever being logged. |
-| `recap` | `facets/recap.md` | 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. |
+| `recap` | `facets/recap.md` | Summarize a task's run-to-run phase transitions — or a task-group's start order, per-brief status, and each task's latest conclusion — then answer free-form questions over the `.okstra` artifacts. Appends each summary/Q&A to `recap-log.jsonl` (task `recap/`, group `.recap/`), and writes agent-authored notes to `notes/` for feeding into later runs. |
 
 ## Step 0: Preflight (shared)
 

package/runtime/skills/okstra-inspect/facets/recap.md

@@ -6,13 +6,16 @@ Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step
 
 Trigger phrases: "okstra recap", "recap", "work summary", "summarize this task", "before/after summary", "explain this work", "task question".
 
-On top of the `.okstra` artifacts accumulated for a single task-id, (a) produce a before/after summary and (b) answer free-form questions about that work. By default it reads only the `.okstra/` subtree (artifact mode). It expands to code mode only when the user explicitly asks to look at the code changes too. This sub-command performs only the `recap/recap-log.jsonl` append and the `notes/` note authoring (recap.5); it never mutates `task-manifest.json` / catalog / timeline.
+On top of the `.okstra` artifacts accumulated for a single task-id — or for every task of one task-group — (a) produce a before/after summary and (b) answer free-form questions about that work. By default it reads only the `.okstra/` subtree (artifact mode). It expands to code mode only when the user explicitly asks to look at the code changes too. This sub-command performs only the `recap-log.jsonl` append and the `notes/` note authoring (recap.5); it never mutates `task-manifest.json` / catalog / timeline / `group-context.md`.
 
 ### recap.1 — Resolve target
 
-The same three forms as `cost` / `errors`: ① full task-key, ② bare token — the standard task-key resolution rule in `SKILL.md` (core), ③ task-root path.
+Two scopes. Decide the scope before resolving anything:
 
-If the user asks for a recap without naming a task (e.g. "summarize this work"), apply the core no-task fallback as-is — do not list only a placeholder form like `<task-group>` and ask back.
+- **Task scope** — the same three forms as `cost` / `errors`: ① full task-key, ② bare token — the standard task-key resolution rule in `SKILL.md` (core), ③ task-root path.
+- **Group scope** — the user names a task-group ("recap the cache group", "how far is the `cache` group", "group progress") or the bare token resolves with every match `Matched via: taskGroup`. Do **not** drop to the N-match picker in that case; carry the group name as `<task-group>` and follow recap.2g / recap.4g below. A group-scope request still takes the one-task path when the user picks a single task from it.
+
+If the user asks for a recap without naming a task or a group (e.g. "summarize this work"), apply the core no-task fallback as-is — do not list only a placeholder form like `<task-group>` and ask back.
 
 ### recap.2 — Assemble the before/after summary
 
@@ -28,11 +31,27 @@ Read the fixed-text `Run count` and repeated `Transition` blocks. Narrate each b
 
 For a transition that has a `Report`, run `okstra render-final-report <Report>` and read the rendered Markdown only when the user wants a deeper summary. Do not open the report data JSON directly and do not render every report automatically.
 
+### recap.2g — Assemble the group status (group scope)
+
+```bash
+okstra model-io recap-input --project-root <projectRoot> --task-group <task-group>
+```
+
+The projection joins three sources and is the only place to read them from — do not re-derive the queue from the brief directory, the catalog, or `group-context.md` by hand:
+
+- the group's briefs give the start order (brief ordinal) and the `waits for` edges;
+- the catalog / each `task-manifest.json` gives the real `Status` (`done` / `in progress` / `not started`), `Progress` (`<phase> (<state>)`), run count, next phase, and report path;
+- the group document's Task Memory gives each recorded task's `Headline`, `Decision N`, `Watch out N`, `Follow-up N`. A task with `Memory run: -` finished before group memory existed — its conclusion lives only in its `Report`.
+
+Read the head lines (`Brief count`, `Task count`, `Next in group`), then the repeated `Queue entry` blocks in order, then the repeated `Task` blocks. Narrate the group as: how many briefs, how many started, which are done, which is next (`Next in group` — `-` means every brief has started), and any `Waits for` that names a ticket not yet done. `Human sections: absent` means the group has no authored `group-context.md` context yet (only okstra's memory region) — say so once when the user asks why the group exists; do not offer to write it here (that is `okstra group-context init` via okstra-brief-gen).
+
+Numbers beyond run count (CPU, wall clock, error totals) are okstra-rollup's; if the user asks for them, point to `/okstra-rollup --task-group <task-group>` instead of summing anything here.
+
 ### recap.3 — Free-form Q&A loop
 
 After the summary output, take the user's free-form questions.
 
-- **artifact mode (default)**: answer only from `.okstra/` artifacts (timeline, task-manifest, that run's final-report). Every factual claim is accompanied by a `path:line` citation to the `.okstra` file.
+- **artifact mode (default)**: answer only from `.okstra/` artifacts (timeline, task-manifest, that run's final-report; in group scope also `.okstra/briefs/<task-group>/group-context.md` and each member task's artifacts). Every factual claim is accompanied by a `path:line` citation to the `.okstra` file.
 - **code mode (opt-in)**: only when the user **explicitly asks** — "look at the code changes / the diff too" — additionally read `git diff` · `git log` from that task's worktree/branch and answer at the code level. Entering recap never by itself switches to code mode.
 
 ### recap.4 — Persist each turn
@@ -48,6 +67,19 @@ okstra recap record <resolved-target> --project-root <projectRoot> \
 
 Put a one-or-two-line summary in `--answer`, not the full answer transcript. If there are multiple citations, repeat `--citation`. Do not silently swallow a recording failure (abnormal exit) — tell the user.
 
+### recap.4g — Persist each turn (group scope)
+
+Same flags, but the group replaces the target and the log lands at `.okstra/tasks/<task-group>/.recap/recap-log.jsonl`:
+
+```bash
+okstra recap record --task-group <task-group> --project-root <projectRoot> \
+  --kind <summary|qa> --mode <artifact|code> \
+  --question "<question or omit>" --answer "<one or two line summary>" \
+  --citation "<path:line>"
+```
+
+`recap note` has no group form — a note belongs to the task whose next run will carry it, so write it against that task-key.
+
 ### recap — Output template
 
 ```markdown
@@ -62,6 +94,22 @@ Before/after summary (runs: <N>):
 <Free-form questions follow. To include code changes, ask "also show me the diff".>
 ```
 
+Group scope:
+
+```markdown
+## okstra Recap — task-group <task-group> (briefs: <Brief count>, started: <Task count>)
+
+| # | task | status | progress | waits for | latest conclusion |
+|---|---|---|---|---|---|
+| 1 | dev-10626-1-… | done | release-handoff (completed) | — | <Headline, or "report only" when Memory run is -> |
+| 2 | dev-10627-2-… | in progress | implementation-option-selection (prepared) | DEV-10642 | <Headline> |
+| 3 | dev-10628-3-… | not started | — | — | — |
+
+Next in group: <Next in group or "every brief has started">
+
+<Free-form questions follow.>
+```
+
 ### recap.5 — Agent-authored notes (`notes/`)
 
 Leave something in `notes/` only when, during recap, you produced an artifact **for the okstra task** — verification evidence, a design/decision draft, an analysis note — that may serve as grounding for future runs, and whose content is **neither a rendered report nor a user decision**.

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

@@ -1,7 +1,7 @@
 ---
 name: okstra-rollup
 description: |
-  Use when the user wants run results from MULTIPLE okstra tasks collected and summarized at once — a task-group digest or a whole-project roll-up, not a single task. Aggregates per-task run count, elapsed time, error count, and latest report path, plus group-level totals and status/category/phase tallies, then synthesizes a cross-task prose summary from the report files. Make sure to use this skill whenever the user mentions "okstra rollup", "rollup", "task-group summary", "group-level report", "collect multiple task results", "whole-project task status summary", "cross-task summary", "consolidated group report", "organize all tasks", "run results all at once", even if they don't say "rollup". For a SINGLE task's report/time/errors/recap use okstra-inspect instead; for a forward-looking work plan over non-done tasks use okstra-schedule-gen.
+  Use when the user wants run results from MULTIPLE okstra tasks collected and summarized at once — a task-group digest or a whole-project roll-up, not a single task. Aggregates per-task run count, elapsed time, error count, and latest report path, plus group-level totals and status/category/phase tallies, then synthesizes a cross-task prose summary from the report files. Make sure to use this skill whenever the user mentions "okstra rollup", "rollup", "task-group summary", "group-level report", "collect multiple task results", "whole-project task status summary", "cross-task summary", "consolidated group report", "organize all tasks", "run results all at once", even if they don't say "rollup". For a SINGLE task's report/time/errors/recap, or "where does the group stand" (per-brief status, what is next), use okstra-inspect; this skill is for the numbers and the cross-task digest. For a forward-looking work plan over non-done tasks use okstra-schedule-gen.
 ---
 
 # OKSTRA Rollup