okstra 0.104.0 → 0.106.0

package/docs/task-process/final-verification.md

@@ -21,10 +21,10 @@
 flowchart TD
     Start[/okstra-run/] --> Common[공통 task identity flow]
     Common --> Type[task-type = final-verification]
-    Type --> Worktree{active task worktree?}
-    Worktree -->|yes| Defaults[Use defaults / Customize]
-    Worktree -->|no| BaseRef[base-ref pick/text]
-    BaseRef --> Defaults
+    Type --> PlanPick[approved plan pick]
+    PlanPick --> Approved[approval marker confirm]
+    Approved --> Stage[stage pick<br/>whole-task or stage number]
+    Stage --> Defaults[Use defaults / Customize]
     Defaults -->|defaults| Workers[worker roster pick<br/>claude/codex/report-writer default]
     Defaults -->|customize| Models[lead + worker model prompts]
     Models --> Extras[directive, related tasks, clarification]
@@ -35,38 +35,47 @@ flowchart TD
 
 `final-verification`은 analyser roster가 있는 non-implementation phase다. 따라서 `Use defaults`를 골라도 worker roster prompt는 계속 나온다. 기본 required workers는 `claude`, `codex`, `report-writer`이고, `antigravity`는 opt-in이다.
 
+이 phase는 `base-ref`를 직접 묻지 않는다. wizard는 approved plan의 Stage Map을 기준으로 whole-task 또는 단일 stage를 선택하고, prepare가 registry/`consumers.jsonl`/git 상태에서 `VERIFICATION_TARGET`을 해소한다.
+
 ## 3. entry gate
 
 ```mermaid
 sequenceDiagram
-    participant Lead as Claude lead
-    participant Brief as task brief
-    participant Impl as implementation final-report
+    participant P as prepare_task_bundle
+    participant C as consumers.jsonl
+    participant Reg as worktree registry
     participant Git as verification worktree
+    participant Lead as Claude lead
 
-    Lead->>Brief: Source Implementation Report section read
-    Lead->>Impl: required sections present?
-    Lead->>Git: inspect same worktree named by report
-    Lead->>Git: git rev-parse HEAD
-    Lead->>Git: git status --short
-    Lead->>Git: git diff --stat <implementation-base>..HEAD
-    Git-->>Lead: verification target snapshot
-    Lead->>Lead: commit list and diff summary match?
+    P->>C: backfill carry and read done rows
+    P->>Reg: resolve task or stage worktree
+    alt whole-task
+        P->>Git: merge done stage commits into task worktree
+        P->>Git: teardown clean stage worktrees/registry keys
+    else single-stage
+        P->>Git: reuse selected stage worktree
+    end
+    P->>Git: resolve base/head/diff stat
+    P-->>Lead: inject VERIFICATION_TARGET
+    Lead->>Lead: verify against injected target only
 ```
 
-lead는 worker dispatch 전에 verification target을 고정한다. 다음 중 하나라도 실패하면 검증하지 않고 `blocked`로 끝내며 `implementation` 또는 `implementation-planning`으로 되돌린다.
+prepare는 worker dispatch 전에 verification target을 고정한다. 다음 중 하나라도 실패하면 lead prompt가 시작되지 않고 `PrepareError`로 멈춘다.
+
+- approved plan의 Stage Map을 읽을 수 없다.
+- whole-task인데 Stage Map의 모든 stage가 `done`이 아니다.
+- whole-task 자동 통합 중 merge conflict가 난다.
+- single-stage인데 선택 stage의 implementation stage worktree가 없거나 dirty다.
+- verification worktree가 `.okstra/` 밖 dirty state다.
 
-- task brief에 `## Source Implementation Report`가 없다.
-- 인용된 implementation final report가 없거나 필수 section이 빠져 있다.
-- report가 named worktree를 가리키는데 lead가 다른 checkout을 보고 있다.
-- implementation report의 commit list / diff summary와 현재 checkout이 맞지 않는다.
-- delivered code change commit이 없다.
+시작된 lead는 `VERIFICATION_TARGET`을 권위로 취급한다. worktree/base/head/stage/source report를 brief에서 다시 고르지 않는다.
 
 ## 4. 검증 실행 흐름
 
 ```mermaid
 flowchart TD
-    Gate[entry gate passed] --> Lead[Claude lead fixes target snapshot]
+    Gate[entry gate passed] --> Target[injected VERIFICATION_TARGET]
+    Target --> Lead[Claude lead confirms target snapshot]
     Lead --> CW[Claude verifier<br/>read-only]
     Lead --> XW[Codex verifier<br/>read-only]
     Lead --> GW{Antigravity opt-in?}
@@ -110,7 +119,7 @@ flowchart TD
 
 `## 7. Final Verdict`에는 `Verdict Token` field가 정확히 하나 들어가야 하며 값은 다음 셋 중 하나다.
 
-- `accepted`: release-handoff로 넘겨도 되는 상태
+- `accepted`: whole-task이면 plain `release-handoff`, single-stage이면 `release-handoff(stage-group)` 후보가 되는 상태
 - `conditional-accept`: 조건을 모두 명시해야 하며, 조건이 gate면 다음 phase를 막는다
 - `blocked`: acceptance blocker가 있어 release-handoff로 갈 수 없는 상태
 
@@ -132,6 +141,7 @@ flowchart TD
 final report에는 최소 다음이 필요하다.
 
 - originating implementation final-report path
+- verification scope(`whole-task` 또는 `single-stage`)와 injected `VERIFICATION_TARGET`
 - inspected worktree path
 - implementation base ref와 run start head SHA
 - quoted commit list / diff summary
@@ -146,15 +156,16 @@ final report에는 최소 다음이 필요하다.
 
 ```mermaid
 flowchart TD
-    FV[final-verification] --> Allowed[read-only inspect/test/validate]
+    FV[final-verification] --> Runtime[prepare-owned whole-task integration<br/>or single-stage target resolution]
+    FV --> Allowed[lead read-only inspect/test/validate]
     FV -. forbidden .-> Edit[source edit or config edit]
     FV -. forbidden .-> Fix[in-run bug fix]
-    FV -. forbidden .-> Mutate[mutating command]
+    FV -. forbidden .-> Mutate[lead-owned mutating command]
     FV -. forbidden .-> Expand[scope expansion]
     FV -. forbidden .-> Hide[hide verifier dissent]
 ```
 
-source edit, follow-up fix, scope expansion은 전부 금지다. 결함을 발견하면 현재 run 안에서 고치지 않고 final report에 blocker로 기록한 뒤 새 `error-analysis` 또는 `implementation-planning` 입력으로 넘긴다.
+whole-task mode의 stage merge/teardown은 prepare가 수행하는 runtime-owned 통합 단계다. 그 이후 lead 검증은 read-only다. source edit, follow-up fix, scope expansion은 전부 금지다. 결함을 발견하면 현재 run 안에서 고치지 않고 final report에 blocker로 기록한 뒤 새 `error-analysis` 또는 `implementation-planning` 입력으로 넘긴다.
 
 ## 8. 확인한 코드
 

package/docs/task-process/implementation.md

@@ -27,8 +27,9 @@ flowchart TD
     BaseRef --> PlanPick
     PlanPick --> Approved{APPROVED marker present?}
     Approved -->|no| Retry[re-prompt same step]
-    Approved -->|yes| Stage[stage pick<br/>auto or number]
-    Stage --> Executor[executor pick<br/>claude/codex/antigravity]
+    Approved -->|yes| Stage[stage multi-pick<br/>ready/active markers]
+    Stage --> Chain[render-args<br/>stage + chain-stages]
+    Chain --> Executor[executor pick<br/>claude/codex/antigravity]
     Executor --> Defaults[Use defaults / Customize]
     Defaults -->|defaults| Confirm
     Defaults -->|customize| Models[lead + executor model + report-writer model]
@@ -37,7 +38,9 @@ flowchart TD
     Confirm --> Render[render-bundle]
 ```
 
-`implementation`은 worker override 질문이 없다. wizard `render_args()`가 `workers`를 빈 문자열로 내보내고, runtime이 profile default roster를 사용한다. 현재 okstra-run wizard 경로는 승인 checkbox를 직접 flip하는 `--approve`를 노출하지 않는다. plan file에는 이미 recognized approval marker가 있어야 한다.
+`implementation`은 worker override 질문이 없다. wizard `render_args()`가 `workers`를 빈 문자열로 내보내고, runtime이 profile default roster를 사용한다. `stage_pick`은 완료/진행중/준비됨/대기 상태를 보여주는 multi-pick이다. 선택한 stage 집합은 의존성 closure와 위상정렬을 거쳐 `chain-stages` CSV가 되고, 각 실제 run은 그중 한 stage만 실행한다.
+
+현재 okstra-run wizard 경로는 승인 checkbox를 직접 flip하는 `--approve`를 노출하지 않는다. plan file에는 이미 recognized approval marker가 있어야 한다.
 
 ## 3. runtime gate
 
@@ -47,16 +50,21 @@ sequenceDiagram
     participant P as prepare_task_bundle
     participant Plan as approved final-report
     participant QA as project.json qaCommands
-    participant Stage as stage validator
+    participant Stage as stage target policy
+    participant Reg as worktree registry
+    participant WT as stage worktree
 
     W->>P: task-type=implementation, approved-plan, stage, executor
     P->>Plan: file exists?
     P->>Plan: approval marker regex matches?
     P->>Plan: unresolved Blocks=approval rows?
-    P->>Stage: validate stage structure
+    P->>Stage: parse Stage Map and recover carry/done rows
+    P->>Reg: read active stage-key reservations
+    P->>Stage: select exactly one ready stage
+    P->>WT: provision stage-N worktree + branch
     P->>QA: validate qaCommands deny-list
     P->>P: executor provider in resolved roster?
-    P->>P: provision/reuse worktree
+    P->>P: namespace run artifacts under stage-N
     P-->>W: prepared implementation prompt or PrepareError
 ```
 
@@ -86,16 +94,21 @@ Executor만 project file을 mutate할 수 있다. verifier는 같은 worktree에
 ```mermaid
 flowchart LR
     Plan[approved plan<br/>Stage Map] --> Parse[parse stage map]
-    Parse --> Done[read consumers.jsonl<br/>done stages]
-    Done --> Resolve{stage arg}
-    Resolve -->|auto| Next[lowest unblocked unfinished stage]
+    Parse --> Done[backfill carry<br/>read consumers.jsonl]
+    Done --> Reserved[read registry<br/>active stage reservations]
+    Reserved --> Resolve{stage arg}
+    Resolve -->|auto| Next[lowest ready<br/>not done/started/reserved]
     Resolve -->|number| Forced[selected stage]
-    Next --> Started[append consumer status=started]
-    Forced --> Started
-    Started --> Run[implementation executes selected stage]
+    Next --> Base[resolve stage base commit]
+    Forced --> Base
+    Base --> WT[create/reuse stage worktree]
+    WT --> Started[append consumer status=started]
+    Started --> Run[implementation executes one selected stage]
 ```
 
-stage 선택은 `auto` 또는 숫자다. 다른 task-type에서 `--stage`가 오면 `PrepareError`다. wizard는 approved plan에서 Stage Map을 parse해 stage picker에 `auto`와 각 stage를 보여준다.
+stage 선택은 `auto` 또는 숫자다. 다른 task-type에서 `--stage`가 오면 `PrepareError`다. runtime은 `consumers.jsonl`의 `done`/`started`와 registry의 active stage-key를 함께 보고 점유 stage를 제외한다.
+
+stage worktree base는 dependency 형태로 정한다. 독립 stage는 첫 implementation 진입 때 고정한 task-key worktree HEAD를 anchor로 삼고, 단일 의존 stage는 선행 stage의 done `head_commit`에서 분기한다. 다중 의존 stage는 모든 선행 done commit이 task-key worktree HEAD의 ancestor인지 확인한 뒤 그 HEAD에서 분기한다.
 
 ## 6. 산출물
 
@@ -113,12 +126,14 @@ flowchart TD
 final report에는 최소 다음이 필요하다.
 
 - approved plan path와 quoted approval marker
+- selected stage, isolated stage worktree path, run artifact path(`runs/implementation/stage-<N>/`)
 - commit SHA, message, plan step mapping
 - diff summary와 per-file summary
 - out-of-plan edits block
 - plan validation command의 실제 stdout/stderr와 exit code
 - TDD failing-then-passing evidence
 - verifier별 independent validation rerun result
+- `carry/stage-<N>.json` evidence sidecar와 `consumers.jsonl` started/done row
 - rollback verification
 - follow-up tasks table
 
@@ -146,4 +161,3 @@ flowchart TD
 - [`validators/validate-implementation-plan-stages.py`](../../validators/validate-implementation-plan-stages.py)
 - [`scripts/okstra_ctl/qa_commands.py`](../../scripts/okstra_ctl/qa_commands.py)
 - [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)
-

package/docs/task-process/release-handoff.md

@@ -14,7 +14,7 @@
 
 ## 1. 목적
 
-`release-handoff`는 `accepted` verdict가 나온 already-committed implementation branch를 push하거나 PR로 넘기는 terminal phase다. 새 commit을 만들지 않고, 검증된 diff를 그대로 포장한다.
+`release-handoff`는 `accepted` verdict가 나온 already-committed implementation 결과를 push하거나 PR로 넘기는 terminal phase다. whole-task mode는 검증된 task branch를 그대로 포장한다. stage-group mode는 선택 stage들을 collector branch에 assemble해 한 PR로 묶을 수 있으며, 이때 생성되는 merge commit은 `okstra handoff assemble`만 만든다.
 
 이 phase는 worker dispatch가 없다. `claude`, `codex`, `report-writer` roster를 쓰지 않으며 Claude lead가 inline으로 git/gh inspection, 사용자 질문, PR draft, final report 작성을 모두 수행한다.
 
@@ -24,7 +24,9 @@
 flowchart TD
     Start[/okstra-run/] --> Common[공통 task identity flow]
     Common --> Type[task-type = release-handoff]
-    Type --> Worktree{active task worktree?}
+    Type --> Plan[approved plan auto/pick]
+    Plan --> Scope[handoff stage pick<br/>whole-task or eligible stages]
+    Scope --> Worktree{active task worktree?}
     Worktree -->|yes| Defaults[Use defaults / Customize]
     Worktree -->|no| BaseRef[base-ref pick/text]
     BaseRef --> Defaults
@@ -32,14 +34,14 @@ flowchart TD
     Defaults -->|customize| Models[lead model prompt]
     Models --> Extras[directive, related tasks, clarification]
     Extras --> Template[PR template override?]
-    Template --> Scope[save template to project/global?]
-    Scope --> Confirm
+    Template --> TemplateScope[save template to project/global?]
+    TemplateScope --> Confirm
     Confirm --> Render[render-bundle]
 ```
 
-`release-handoff`는 worker roster prompt가 없다. wizard의 `render_args()`는 `pr-template-path`를 release-handoff일 때만 포함하고, runtime은 worker list를 강제로 empty로 만든다.
+`release-handoff`는 worker roster prompt가 없다. wizard의 `render_args()`는 `pr-template-path`를 release-handoff일 때만 포함하고, runtime은 worker list를 강제로 empty로 만든다. scope 선택은 prepare 전에 끝난다. whole-task는 accepted whole-task verification report가 있어야 하고, stage-group은 accepted single-stage verification으로 `verified` 처리됐지만 아직 `pr`로 덮이지 않은 stage만 후보가 된다.
 
-주의할 점은 이 phase도 task worktree provisioning 대상이라는 것이다. 정상 흐름은 같은 task-key의 implementation/final-verification worktree를 재사용한다. 새 task로 시작하면 새 branch가 만들어질 수 있고, entry gate의 "implementation commit exists" 조건에서 막힐 가능성이 높다.
+주의할 점은 이 phase도 task worktree provisioning 대상이라는 것이다. 정상 흐름은 같은 task-key의 implementation/final-verification 결과를 재사용한다. 새 task로 시작하면 새 branch가 만들어질 수 있고, entry gate의 "implementation commit exists" 조건에서 막힐 가능성이 높다.
 
 ## 3. prepare 단계
 
@@ -72,7 +74,10 @@ flowchart TD
     Source -->|no| Block[blocked<br/>route final-verification]
     Source -->|yes| Verdict{Verdict Token == accepted?}
     Verdict -->|no| Block
-    Verdict -->|yes| Status{git status --short clean?}
+    Verdict -->|yes| Mode{HANDOFF_MODE}
+    Mode -->|stage-group| Eligible[each selected stage<br/>verified and not in PR]
+    Mode -->|whole-task| Status{git status --short clean?}
+    Eligible --> Status
     Status -->|no| Dirty[blocked<br/>dirty tree]
     Status -->|yes| Branch{current branch is base branch?}
     Branch -->|yes| BaseBlock[blocked<br/>never operate on base branch]
@@ -84,7 +89,8 @@ flowchart TD
 lead는 사용자에게 push/PR 여부를 묻기 전에 다음을 확인한다.
 
 - prepare 가 생성한 input 문서(`release-handoff-input.md`)의 `## Source Verification Report` 가 모드(`HANDOFF_MODE`)와 인용 보고서 표를 담고 있다. brief 는 entry phase 의 입력물이라 release-handoff 에는 없다 — 사용자의 stage 선택은 wizard `handoff_stage_pick` 또는 CLI `--stages` 로 prepare 전에 끝난다.
-- 인용된 각 report 의 `## 7. Final Verdict`에 `Verdict Token = accepted`가 정확히 있다.
+- whole-task mode에서는 인용 report가 `verificationScope=whole-task`이고 `Verdict Token = accepted`여야 한다.
+- stage-group mode에서는 인용된 각 single-stage report가 `Verdict Token = accepted`여야 하며, prepare/`okstra handoff assemble`이 eligibility와 dependency closure를 다시 강제한다.
 - working tree가 clean이다.
 - 현재 branch가 `main`, `master`, `prod`, `preprod`, `staging`, `dev` 같은 base branch가 아니다.
 - `<base>..HEAD` commit range가 비어 있지 않다.
@@ -99,7 +105,11 @@ stateDiagram-v2
     Gate --> Q1: action selection
     Q1 --> LocalCheckout: local checkout
     Q1 --> Skip: skip
-    Q1 --> Q2: push + PR
+    Q1 --> Q2: push + PR whole-task
+    Q1 --> G2: push + PR stage-group
+    state "base select + stage confirmation / okstra handoff assemble" as Assemble
+    G2 --> Assemble
+    Assemble --> Q3: collector branch ready
     Q2 --> Probe: choose PR base
     Probe --> Q3: no conflict
     Probe --> Conflict: conflict detected
@@ -124,6 +134,8 @@ stateDiagram-v2
 
 `push + PR`에서만 merge-conflict probe를 한다.
 
+stage-group mode에서는 `local checkout`을 제공하지 않는다. `push + PR`을 고른 뒤 PR base를 먼저 선택하고, 이미 고정된 `HANDOFF_STAGES`를 확인한 다음 `okstra handoff assemble`이 collector branch를 만든다. 이후 conflict probe와 PR title/body 확인은 collector branch를 head로 삼는다.
+
 ```mermaid
 flowchart TD
     PushPR[push + PR selected] --> Fetch[git fetch origin chosen-base]
@@ -170,11 +182,13 @@ flowchart TD
 final report에는 최소 다음이 필요하다.
 
 - originating final-verification report path와 quoted `accepted` verdict row
+- handoff mode(`whole-task` 또는 `stage-group`)와 selected stages
 - feature branch와 run start `git status --short`
 - 사용자 선택 기록
 - 실행한 모든 git/gh command와 exit code
 - implementation commit list
 - merge-conflict probe 결과
+- stage-group이면 collector branch, merge commit SHA, dependency-closure 결과
 - PR 생성, 재사용, 생략 결과
 - routing recommendation `done`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.104.0",
+  "version": "0.106.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.104.0",
-  "builtAt": "2026-06-27T12:43:11.068Z",
+  "package": "0.106.0",
+  "builtAt": "2026-06-27T16:35:08.703Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/container_registry.py

@@ -4,54 +4,33 @@ docker 라벨은 컨테이너 존재 여부의 기준값(SSOT)이지만 tmux ses
 findings 파일 경로 같은 운영 메타데이터는 추적하지 못한다. 이 모듈은 task root
 하위 ``container/registry.json`` 에 그런 보조 정보를 가벼운 dict 로 보관한다.
 
-flock + tmp+``os.replace`` 원자 쓰기 idiom 은 ``worktree_registry`` 의
-``_registry_lock``/``_load``/``_save`` 를 그대로 복제했고, lock/registry 경로만
-``paths.container_paths()`` 로 해소해 전역 ``~/.okstra/worktrees/registry.json``
-과 분리한다. dict 구조는 ``{"services": {<svc>: {session_name, pane_id,
-findings_path}}}`` 한 가지뿐 — worktree_registry 의 dataclass 는 복제하지 않는다.
+flock + tmp+``os.replace`` 원자 쓰기 idiom 은 ``json_registry`` 의 공용
+Interface 를 사용하고, lock/registry 경로만 ``paths.container_paths()`` 로
+해소해 전역 ``~/.okstra/worktrees/registry.json`` 과 분리한다. dict 구조는
+``{"services": {<svc>: {session_name, pane_id, findings_path}}}`` 한 가지뿐 —
+worktree_registry 의 dataclass 는 복제하지 않는다.
 """
 from __future__ import annotations
 
-import contextlib
-import fcntl
-import json
-import os
 from pathlib import Path
 
+from .json_registry import load_registry_json, registry_lock, save_registry_json
 from . import paths
 
 
-@contextlib.contextmanager
 def _registry_lock(lock_path: Path):
-    """``container/registry.json.lock`` 에 대한 배타 flock. worktree_registry 의
-    ``_registry_lock`` 과 동일한 패턴이되 경로를 인자로 받는다(전역 lock 과 분리)."""
-    lock_path.parent.mkdir(parents=True, exist_ok=True)
-    if not lock_path.exists():
-        lock_path.touch()
-    f = lock_path.open("r+")
-    try:
-        fcntl.flock(f.fileno(), fcntl.LOCK_EX)
-        yield
-    finally:
-        f.close()
+    """``container/registry.json.lock`` 에 대한 배타 flock."""
+    return registry_lock(lock_path)
 
 
 def _load(registry_path: Path) -> dict:
-    if not registry_path.exists():
-        return {"services": {}}
-    try:
-        data = json.loads(registry_path.read_text())
-    except (OSError, json.JSONDecodeError):
-        return {"services": {}}
+    data = load_registry_json(registry_path, lambda: {"services": {}})
     data.setdefault("services", {})
     return data
 
 
 def _save(registry_path: Path, data: dict) -> None:
-    registry_path.parent.mkdir(parents=True, exist_ok=True)
-    tmp = registry_path.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
-    os.replace(tmp, registry_path)
+    save_registry_json(registry_path, data)
 
 
 def reserve(

package/runtime/python/okstra_ctl/json_registry.py

@@ -0,0 +1,43 @@
+"""Shared flock + atomic JSON persistence for small okstra registries."""
+from __future__ import annotations
+
+import contextlib
+import fcntl
+import json
+import os
+from collections.abc import Callable, Iterator
+from pathlib import Path
+
+
+@contextlib.contextmanager
+def registry_lock(lock_path: Path) -> Iterator[None]:
+    """Hold an exclusive flock on ``lock_path``."""
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    if not lock_path.exists():
+        lock_path.touch()
+    handle = lock_path.open("r+")
+    try:
+        fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+        yield
+    finally:
+        fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+        handle.close()
+
+
+def load_registry_json(path: Path, default_factory: Callable[[], dict]) -> dict:
+    """Load a registry dict, or a fresh default when absent/corrupt."""
+    if not path.exists():
+        return default_factory()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return default_factory()
+    return data if isinstance(data, dict) else default_factory()
+
+
+def save_registry_json(path: Path, data: dict) -> None:
+    """Persist registry JSON via temp file + ``os.replace``."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    os.replace(tmp, path)

package/runtime/python/okstra_ctl/rollup.py

@@ -0,0 +1,113 @@
+"""Read-side cross-task roll-up for a task-group (or the whole project).
+
+단일 task 집계기(time-report / error-report / recap)는 task-root 하나만 받는다.
+이 모듈은 그 위에서 catalog 를 task-group 단위로 fan-out 해 task 별 run 수·소요
+시간·에러 수·report 경로를 모으고, group 차원의 합계/분포를 deterministic 하게
+roll-up 한다. report 본문 종합(자연어 요약)은 LLM(skill)에 남긴다 — 여기서는
+report 경로만 노출한다. time-report 와 동일하게 raw ms 를 출력하고 HH:MM:SS
+포맷·Markdown 표 렌더는 호출자(skill)에 위임한다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from okstra_ctl.error_log_core import glob_error_logs, parse_records
+from okstra_ctl.time_report import _load_runs, aggregate_time
+from okstra_project import (
+    ResolverError,
+    list_project_tasks,
+    resolve_project_root,
+)
+
+
+def _collect_task(entry: dict, project_root: Path) -> dict:
+    """list_project_tasks entry → roll-up 한 줄. catalog 상태 필드 + time/error 측정.
+
+    runCount 는 timeline 의 전체 run 수(usable durationMs 없는 run 도 포함)이고
+    cpuSumMs/wallClockMs 는 durationMs 가 있는 run 만 반영하므로 0 일 수 있다.
+    """
+    task_root = Path(entry["_resolvedTaskRoot"])
+    runs = _load_runs(task_root)
+    time_agg = aggregate_time(runs, project_root)
+    records, _ = parse_records(glob_error_logs(task_root))
+    return {
+        "taskKey": entry.get("taskKey", ""),
+        "taskGroup": entry.get("taskGroup", ""),
+        "taskId": entry.get("taskId", ""),
+        "taskType": entry.get("taskType", ""),
+        "workCategory": entry.get("workCategory", "") or "unknown",
+        "workStatus": entry.get("workStatus", "") or "unknown",
+        "currentPhase": entry.get("currentPhase", ""),
+        "currentPhaseState": entry.get("currentPhaseState", ""),
+        "nextRecommendedPhase": entry.get("nextRecommendedPhase", ""),
+        "latestRunStatus": entry.get("latestRunStatus", ""),
+        "updatedAt": entry.get("updatedAt", ""),
+        "reportPath": entry.get("latestReportPath", ""),
+        "runCount": len(runs),
+        "cpuSumMs": time_agg["grandTotal"]["cpuSumMs"],
+        "wallClockMs": sum(r["wallClockMs"] for r in time_agg["perRunWallClock"]),
+        "errorCount": len(records),
+    }
+
+
+def _tally(tasks: list[dict], key: str) -> dict:
+    """task 들의 한 필드를 값별 개수로. 빈 값은 'unknown' 으로 접는다."""
+    counts: dict[str, int] = {}
+    for task in tasks:
+        bucket = task.get(key) or "unknown"
+        counts[bucket] = counts.get(bucket, 0) + 1
+    return dict(sorted(counts.items()))
+
+
+def build_rollup(project_root: Path, task_group: str | None) -> dict:
+    entries = list_project_tasks(project_root, task_group=task_group or None)
+    tasks = [_collect_task(e, project_root) for e in entries]
+    totals = {
+        "runs": sum(t["runCount"] for t in tasks),
+        "cpuSumMs": sum(t["cpuSumMs"] for t in tasks),
+        "wallClockMs": sum(t["wallClockMs"] for t in tasks),
+        "errors": sum(t["errorCount"] for t in tasks),
+        "byWorkStatus": _tally(tasks, "workStatus"),
+        "byWorkCategory": _tally(tasks, "workCategory"),
+        "byCurrentPhase": _tally(tasks, "currentPhase"),
+        "byTaskType": _tally(tasks, "taskType"),
+    }
+    return {
+        "ok": True,
+        "projectRoot": str(project_root),
+        "taskGroup": task_group or None,
+        "taskCount": len(tasks),
+        "tasks": tasks,
+        "totals": totals,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="okstra rollup",
+        description="Roll up run results across a task-group's tasks (raw ms).")
+    parser.add_argument("--task-group", default="",
+                        help="scope to this task-group (default: whole project catalog)")
+    parser.add_argument("--project-root", default="")
+    parser.add_argument("--cwd", default=".")
+    parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
+    args = parser.parse_args(argv)
+
+    try:
+        project_root = Path(
+            resolve_project_root(explicit_root=args.project_root, cwd=args.cwd)
+        ).resolve()
+    except ResolverError as exc:
+        print(json.dumps({"ok": False, "stage": "resolve", "reason": str(exc)}))
+        return 2
+
+    result = build_rollup(project_root, args.task_group)
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/worktree_registry.py

@@ -23,10 +23,6 @@ file is useful for debugging.
 """
 from __future__ import annotations
 
-import contextlib
-import fcntl
-import json
-import os
 import time
 from dataclasses import dataclass
 from pathlib import Path
@@ -34,6 +30,8 @@ from typing import Optional
 
 from okstra_project.dirs import okstra_home
 
+from .json_registry import load_registry_json, registry_lock, save_registry_json
+
 
 REGISTRY_FILENAME = "registry.json"
 LOCK_FILENAME = "registry.lock"
@@ -77,23 +75,9 @@ class WorktreeEntry:
     stages: Optional[list] = None
 
 
-@contextlib.contextmanager
 def _registry_lock():
-    """Exclusive flock on `<worktrees>/registry.lock`. Mirrors the
-    `central_lock` pattern from `locks.py` but scoped to the registry
-    so we do not serialise unrelated central operations.
-    """
-    root = _okstra_worktrees_dir()
-    root.mkdir(parents=True, exist_ok=True)
-    lockfile = root / LOCK_FILENAME
-    if not lockfile.exists():
-        lockfile.touch()
-    f = lockfile.open("r+")
-    try:
-        fcntl.flock(f.fileno(), fcntl.LOCK_EX)
-        yield
-    finally:
-        f.close()
+    """Exclusive flock on `<worktrees>/registry.lock`."""
+    return registry_lock(_okstra_worktrees_dir() / LOCK_FILENAME)
 
 
 def _registry_path() -> Path:
@@ -101,24 +85,14 @@ def _registry_path() -> Path:
 
 
 def _load() -> dict:
-    p = _registry_path()
-    if not p.exists():
-        return {"tasks": {}, "branches": {}}
-    try:
-        data = json.loads(p.read_text())
-    except (OSError, json.JSONDecodeError):
-        return {"tasks": {}, "branches": {}}
+    data = load_registry_json(_registry_path(), lambda: {"tasks": {}, "branches": {}})
     data.setdefault("tasks", {})
     data.setdefault("branches", {})
     return data
 
 
 def _save(data: dict) -> None:
-    p = _registry_path()
-    p.parent.mkdir(parents=True, exist_ok=True)
-    tmp = p.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
-    os.replace(tmp, p)
+    save_registry_json(_registry_path(), data)
 
 
 def lookup(